Java 2 Ada - Tag LaTeX2018-02-18T09:17:00+00:00Stephane Carrezurn:md5:d12e23c53b2436d6becce3d51ddbdf38AWAWriting an Ada programmer's guide with Dynamo, Pandoc and Read the Docsurn:md5:50d46d8782cab0fff7bd1a5a7923daa82018-02-18T09:17:00+00:002018-02-18T09:17:00+00:00Stephane CarrezAdaMarkdownDocumentationLaTeX
<div class="post-text"><p><div class="wiki-img-center"><div class="wiki-img-inner"><img src="/images/Ada/user-guide-generation.png" longdesc="User Guide Generation" alt="user-guide-generation.png"></img></div></div></p><h3>Writing user's guide in Ada specification</h3><p>Since I often forget to update some external documentation, I've found convenient to have it close to the implementation within the code. I'm not speaking about a reference documentation that explains every type, function or procedure provided by an Ada package. I'm talking about a programmer's guide.</p><p>The solution I've used is to write a small programmer's guide within some Ada package specification. The programmer's guide is written within comments before the package declaration. It is then extracted and merged with other package documentation to create the final programmer's guide. One benefit in having such small programmer's guide in the package specification is that it also brings some piece of documentation to developers: the user's guide is close to the specification.</p><p>The documentation is written using <a href="http://commonmark.org/">Markdown</a> syntax and put before the package declaration. The extraction tool recognizes a number of formatting patterns and commands that help in merging the different pieces in one or several files.</p><h4>Section headers</h4><p>First the small programmer's guide must start with a section header introduced by at least one <code>=</code> (equal) sign. The programmer's guide documentation ends with the start of the Ada <code>package</code> declaration. Unlike <a href="http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/">AdaBrowse</a> and <a href="http://adadoc.sourceforge.net/index.html">AdaDoc</a>, the package specification is not parsed and not used.</p><pre><code class="lang-Ada">-- = Streams =
-- The `Util.Streams` package provides several types and operations to allow the
-- composition of input and output streams. Input streams can be chained together so that
-- ...
...
package Util.Streams is ...
</code></pre><p>When an Ada package specification includes such comment, a documentation file is created. The generated file name is derived from the package name found after the <code>package</code> keyword. The <code>.</code> (dot) are replaced by <code>_</code> (underscore) and the <code>.md</code> extension is added. In this example, the generated file is <code>Util_Streams.md</code>.</p><h4>Merging with @include <file></h4><p>The @<code>include</code> command indicates that the small programmer's guide from the given file must be included. For example, the Streams support of Ada Utility Library is provided by several packages, each being a child of the <code>Util.Streams</code> package. The different pieces of the programmer's guide are merged together by using the following comments:</p><pre><code class="lang-ada">-- @include util-streams-buffered.ads
-- @include util-streams-texts.ads
-- @include util-streams-files.ads
-- @include util-streams-pipes.ads
-- @include util-streams-sockets.ads
-- @include util-streams-raw.ads
-- @include util-streams-buffered-encoders.ads
</code></pre><h4>Autolink</h4><p>To avoid having links in the Ada comments, an auto-link feature is used so that some words or short sentences can be turned into links automatically. The auto-link feature works by using a simple text file that indicates words or sequence or words that should be changed to a link. The text file contains one link definition per line, composed of a set of words that must match and the associated link.</p><pre><code>Java Bean https://en.wikipedia.org/wiki/JavaBean
Java Log4j https://logging.apache.org/log4j/2.x/
Log4cxx https://logging.apache.org/log4cxx/latest_stable/index.html
RFC7231 https://tools.ietf.org/html/rfc7231
</code></pre><p>The auto-link feature is very basic. To match a link, a sequence of several words must be present on the same comment line. For example, the following documentation extract:</p><pre><code class="lang-ada">-- = Logging =
-- The `Util.Log` package and children provide a simple logging framework inspired
-- from the Java Log4j library. It is intended to provide a subset of logging features
</code></pre><p>will generate the following <a href="http://commonmark.org/">Markdown</a> extract with a link for the "<code>Java Log4j</code>" word sequence:</p><pre><code># Logging
The `Util.Log` package and children provide a simple logging framework inspired
from the [Java Log4j](https://logging.apache.org/log4j/2.x/) library...
</code></pre><h4>Code extract</h4><p>Having code examples is important for a programmer's guide and I've made the choice to have them as part of the comment. The extraction tool recognizes them by assuming that they are introduced by an empty line and indented by at least 4 spaces. The code extractor will use the Markdown fenced code block (```) to enclose them.</p><pre><code class="lang-ada">-- is free but using the full package name is helpful to control precisely the logs.
--
-- with Util.Log.Loggers;
-- package body X.Y is
-- Log : constant Util.Log.Loggers := Util.Log.Loggers.Create ("X.Y");
-- end X.Y;
--
-- == Logger Messages ==
</code></pre><h3>Extracting documentation from Ada specification</h3><p>Once the documentation is written, the <a href="https://github.com/stcarrez/dynamo">Dynamo</a> command is used to extract, merge and generate the documentation. The <code>build-doc</code> sub-command scans the project files, reading the Ada specification, some project XML files and generates the documentation in <a href="http://commonmark.org/">Markdown</a> format. The <code>-pandoc</code> option tells the documentation generator to write the documentation for a book oriented organization formatted with <a href="https://pandoc.org/">Pandoc</a>. It will generate them in the <code>docs</code> directory.</p><pre><code>dynamo build-doc -pandoc docs
</code></pre><h3>Putting it all together</h3><p><a href="https://pandoc.org/">Pandoc</a> being a versatile document converter, it allows to format all the generated documentation with some other files and produce a final PDF document. Several files are not generated by <a href="https://github.com/stcarrez/dynamo">Dynamo</a> and they are written either as LaTeX (<code>pagebreak.tex</code>) or <a href="http://commonmark.org/">Markdown</a>, for example the cover page, the introduction and installation chapters.</p><p>By using a custom LaTeX template (eisvogel.tex) and using several configuration option some nice PDF is generated.</p><pre><code>pandoc -f markdown -o util-book.pdf --listings --number-sections \
--toc --template=./docs/eisvogel.tex docs/title.md docs/pagebreak.tex \
docs/intro.md docs/pagebreak.tex docs/Installation.md docs/pagebreak.tex \
docs/Util_Log.md docs/pagebreak.tex docs/Util_Properties.md docs/pagebreak.tex \
docs/Util_Dates.md doc/pagebreak.tex docs/Util_Beans.md docs/pagebreak.tex \
docs/Util_Http.md docs/pagebreak.tex docs/Util_Streams.md docs/pagebreak.tex \
docs/Util_Encoders.md docs/pagebreak.tex docs/Util_Events_Timers.md \
docs/pagebreak.tex docs/Util_Measures.md
</code></pre><p>Here is the final PDF file: <a href="http://download.vacs.fr/ada-util/util-book.pdf">Ada Utility Library Programmer's Guide</a></p><h3>Publishing the programmer's guide</h3><p><a href="https://readthedocs.org/">Read the Docs</a> offers a free documentation hosting with a complete build and publication environment. They are able to connect to a GitHub repository and be notified each time some changes are pushed to build automatically the documentation.</p><p>The documentation is produced by <a href="http://www.mkdocs.org">MkDocs</a> and the <code>mkdocs.yml</code> configuration file allows to configure how the documentation is built, organized and presented:</p><pre><code>site_name: Ada Utility Library
docs_dir: doc
pages:
- Introduction: index.md
- Installation: Installation.md
- Log: Util_Log.md
- Properties: Util_Properties.md
- Dates: Util_Dates.md
- Ada Beans: Util_Beans.md
- HTTP: Util_Http.md
- Streams: Util_Streams.md
- Encoders: Util_Encoders.md
- Measures: Util_Measures.md
- Timers: Util_Events_Timers.md
theme: readthedocs
</code></pre><p>Here is the final programmer's guide: <a href="http://ada-util.readthedocs.io/en/latest/">Ada Utility Library Users' Guide</a>.</p><h3>Conclusion</h3><p>I've found quite useful to write the programmer's guide within the Ada specification. Doing so also helps during the design of a new package because it forces to think a little bit on how the package is going to be used. There are some drawbacks in using this model:</p><ul><li>Each time the documentation must be fixed, the Ada specification file is modified,</li><li>The layout of a programmer's guide does not always follow a package organization,</li><li>Merging the documentation from different parts could bring some complexity when you have to find out where some documentation actually comes from.</li></ul></div>