Quantcast

Ascii Doctor Hybrid approaches to create technical documentation

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Ascii Doctor Hybrid approaches to create technical documentation

MattAdamson
All,

Currently we use ascii doctor for our REST API documentation however I was considering if we should adopt and use  for all technical documentation i.e. covering our public internal Java API and also database documentation which groups require knowledge of in our organisation.

I know JavaDoc tools exist already to produce documents for JavaDoc parsed files. Perhaps we could import Java Doc information within ascii doc but also supplement with other ascii doc generated adoc files / mark up e.g. when discussing a few components. Could we then link to the Java files / JavaDoc documentation within ascii doc?

We could then also link to the existing Ascii Doc REST API documentations e.g. that could link to some key internal JavaDoc APIs used for an "internal" developer audience. I know with ascii doc we can use macro #ifdef support to add content based on certain macros defined too e.g. #ifdef internaldevguide.

Have others used Ascii Doctor in a similar way across their product areas and experiences to share? I'm passionate about Ascii Doc and have created a custom extension but also mindful of using the right tool for the right job.

Thanks
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ascii Doctor Hybrid approaches to create technical documentation

prudhomm
Along the same lines, I was wondering if asciidoc could be used together with doxygen (http://doxygen.org) which is used a lot to generate technical documentation.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Ascii Doctor Hybrid approaches to create technical documentation

johncarl81
Matt,

We have two options to fit your needs and I'm curious how close they match your vision.

First, we have Asciidoclet, which allows you to write Javadocs in Asciidoc format and renders the output into the standard Javadoc html.  This includes a number of benefits including the minimal code-readable syntax and support for Asciidoc plugins.  See this for examples.

Second, a related project we've been putting together is exportdoclet, which allows you to export javadoc comments into asciidoc tagged files  The intention is to allow you to reference your javadoc comments within via asciidoc include statements.

Let me know what you think.
Loading...