Ascii Doctor Hybrid approaches to create technical documentation
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.
Re: Ascii Doctor Hybrid approaches to create technical documentation
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.