Markdown in Anuket

• good community choice to bootstrap our documentation as it’s easy to read and write
• big gaps between its capabilities and the content expected in our GSMA documents (table of contents, internal references, captions, etc.)
• huge extra work to update manually all hardcoded elements (table of contents, the title numbering, all internal and external references, etc.)

Lots of wrong references and dead links

Markdown to GSMA

• conversion to docx partially done via pandoc
• huge manual post-processing to remove all internal links, all hardcoded elements, HTML code and many other bugs in our source code
• GSMA and Anuket documents unsynced as a few post-processing changes hadn’t been backported to Github

it works once but there is room for improvement

RST in Anuket Moselle

• converted all files to rst via pandoc too
• removed all hardcoded elements in our code
• leveraged intersphinx and the numref role to properly handle our references
• used the table rst directives to ease rendering and editing the content
• setup many jobs verifying syntax, all links and the rendering for all patchset proposals

our documentation is now continuously verified

demo

git clone https://github.com/cntt-n/CNTT.git &&
cd CNTT &&
git checkout stable/moselle &&
cd doc/ref_arch/openstack &&
tox &&
cd build &&
make

Please see RA1 gate

what’s next?

• to finish wrapping our code and to fix a few minor issues when rendering PDF
• to leverage the glossary directive for both acronyms and definitions
  
• to collect all the official bibtex files (see RFC2544) and to include them via the bibliography directive
• to integrate a GSMA Sphinx/Latex theme

close to a full e2e documenation build!

Open questions

• is there any Sphinx/LaTeX theme for GSMA?
• how much can we diverge from the docx template? what’s mandatory? optional?
• what about the GSMA particularities? all references should rather be at the end of the document, the table captions on top of it, etc.

we need your help here!