Dokümantasyon, tam olarak bir geliştiricinin favori çocuğu değildir. Çoğunlukla açık kaynaklı projeler, genellikle uygulama için doğru olmayan zayıf belgelerden muzdariptir, ancak ticari yazılım da bir istisna değildir. Red Hat bunu uzun zamandır fark etti ve proje belgelendirmesini basitleştirmek için bir dizi fikir buldu. JBoss Test Denetim projesi bunlardan sadece bir tanesidir. Arquillian entegrasyon test paketi bağlamında, farklı formatlardan kullanıcı belgeleri oluşturmak için Awestruct ile birçok çalışma yapılmıştır. Ve O’Reilly gibi yayıncılar bile Atlas gibi sistemlerle belgelemeye yönelik geliştirme odaklı bir yaklaşıma güveniyor.
Tüm yaklaşımların ortak noktası, dokümantasyonun kolayca oluşturulabilmesi ve dolayısıyla onu yazmak veya yayınlamak için ekstra bir çaba gerektirmemesidir. Nefret edilen kelime işlemci programı Word hiç kullanılmıyor. Tüm yaklaşımlar basit bir sayfa açıklama diline dayanmaktadır. Haml, Markdown veya YAML sıklıkla kullanılır. Github, mesajlar, sorunlar (sorunlar) ve yorumlar için Markdown’ın GFM adlı genişletilmiş bir sürümünü kullanır.
Bir biçimlendirme dilini unuttum: AsciiDoc formatı. 2002’de Python’da yazılan proje iki şey getiriyor: bir biçimlendirme dili ve bu dili HTML, PDF, EPUB veya kılavuz sayfaları gibi diğer çeşitli biçimlere dönüştürme yaklaşımı. Bu yaklaşım oldukça uzun bir süredir piyasadaydı, ancak seçilen uygulama nedeniyle Java dünyasında geniş bir yayılım bulamadı. Yaklaşık bir yıl önce (ilk taahhüt 2012/01/06) GitHub’dan Ryan Waldron (@erebor) ve Red Hat’tan Dan Allen (@mojavelinux), açıkça geliştirmek amacıyla Asciidoctor adlı bir Ruby bağlantı noktası başlattı. Ve doğrudan bir özellik karşılaştırmasının gösterdiği gibi, bu oldukça iyi yapılmış.
Sürüm 0.1.4 daha yeni yayınlandı. Son sürümden yaklaşık dört ay sonra, ürüne 90 hata düzeltmesi ve iyileştirme aktı. %15 hızlanma, 16.000 satırlık bir HTML kitabını 0,85 saniyeden daha kısa sürede oluşturabileceği anlamına gelir. Bu arada, birçok açık kaynak projesi yayın formatına ve sürecine dönüştürüldü. Groovy, Spring XD, Spring Security, OpenShift Origin, Neo4j, CRaSH ve RichFaces gibi eski favoriler dahil.
Başlamayı kolaylaştırmak için artık kapsamlı bir kullanım kılavuzu da mevcuttur. Asciidoctor için Java entegrasyonu da bir süredir mevcuttu. Bununla, AsciiDoc belgeleri doğrudan Java’da oluşturulabilir. Yani bir Javadoc uyarlamasına giden yol çok uzak değildi. Asciidoclet ile Javadoc yorumları artık AsciiDoc’ta da yazılabilir. Ve tabii ki ilgili Maven ve Gradle eklentileri de mevcuttur.
İlgili bir AsciiDoc belgesini Asciidoctor ile dönüştürmenin ne kadar kolay olduğunu hızlı bir şekilde deneyimlemek istiyorsanız, aşağıdakileri kullanabilirsiniz. pom.xml kullanım:
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.version}</version>
<configuration>
<backend>html</backend>
</configuration>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Şimdi uzantılı başka bir dosya .adoc VEYA .asciidoc dizinde kaynakmainasciidoc, ve gitmeye hazırsın. Altında hedefoluşturulan-belgeler oluşturulan HTML dosyası sona erer. Şablonlar ve resimlerle çalışmak mümkündür, ancak elle yapılması gerekir. Awestruct burada biraz daha rahatlık sunuyor.
Bu araçlarla artık mazeret yok: hızlı ve kolay bir şekilde iyi belgeler oluşturabilirsiniz. İyi belgeler!
()
Haberin Sonu
Tüm yaklaşımların ortak noktası, dokümantasyonun kolayca oluşturulabilmesi ve dolayısıyla onu yazmak veya yayınlamak için ekstra bir çaba gerektirmemesidir. Nefret edilen kelime işlemci programı Word hiç kullanılmıyor. Tüm yaklaşımlar basit bir sayfa açıklama diline dayanmaktadır. Haml, Markdown veya YAML sıklıkla kullanılır. Github, mesajlar, sorunlar (sorunlar) ve yorumlar için Markdown’ın GFM adlı genişletilmiş bir sürümünü kullanır.
Bir biçimlendirme dilini unuttum: AsciiDoc formatı. 2002’de Python’da yazılan proje iki şey getiriyor: bir biçimlendirme dili ve bu dili HTML, PDF, EPUB veya kılavuz sayfaları gibi diğer çeşitli biçimlere dönüştürme yaklaşımı. Bu yaklaşım oldukça uzun bir süredir piyasadaydı, ancak seçilen uygulama nedeniyle Java dünyasında geniş bir yayılım bulamadı. Yaklaşık bir yıl önce (ilk taahhüt 2012/01/06) GitHub’dan Ryan Waldron (@erebor) ve Red Hat’tan Dan Allen (@mojavelinux), açıkça geliştirmek amacıyla Asciidoctor adlı bir Ruby bağlantı noktası başlattı. Ve doğrudan bir özellik karşılaştırmasının gösterdiği gibi, bu oldukça iyi yapılmış.
Sürüm 0.1.4 daha yeni yayınlandı. Son sürümden yaklaşık dört ay sonra, ürüne 90 hata düzeltmesi ve iyileştirme aktı. %15 hızlanma, 16.000 satırlık bir HTML kitabını 0,85 saniyeden daha kısa sürede oluşturabileceği anlamına gelir. Bu arada, birçok açık kaynak projesi yayın formatına ve sürecine dönüştürüldü. Groovy, Spring XD, Spring Security, OpenShift Origin, Neo4j, CRaSH ve RichFaces gibi eski favoriler dahil.
Başlamayı kolaylaştırmak için artık kapsamlı bir kullanım kılavuzu da mevcuttur. Asciidoctor için Java entegrasyonu da bir süredir mevcuttu. Bununla, AsciiDoc belgeleri doğrudan Java’da oluşturulabilir. Yani bir Javadoc uyarlamasına giden yol çok uzak değildi. Asciidoclet ile Javadoc yorumları artık AsciiDoc’ta da yazılabilir. Ve tabii ki ilgili Maven ve Gradle eklentileri de mevcuttur.
İlgili bir AsciiDoc belgesini Asciidoctor ile dönüştürmenin ne kadar kolay olduğunu hızlı bir şekilde deneyimlemek istiyorsanız, aşağıdakileri kullanabilirsiniz. pom.xml kullanım:
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.version}</version>
<configuration>
<backend>html</backend>
</configuration>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
Şimdi uzantılı başka bir dosya .adoc VEYA .asciidoc dizinde kaynakmainasciidoc, ve gitmeye hazırsın. Altında hedefoluşturulan-belgeler oluşturulan HTML dosyası sona erer. Şablonlar ve resimlerle çalışmak mümkündür, ancak elle yapılması gerekir. Awestruct burada biraz daha rahatlık sunuyor.
Bu araçlarla artık mazeret yok: hızlı ve kolay bir şekilde iyi belgeler oluşturabilirsiniz. İyi belgeler!
()
Haberin Sonu