Following OITF#12

• GSMA hasn’t provided any Sphinx/LaTex template since London meetings
• the GSMA documentation review is fully hardcoded to docx (precisely diff between docx) and there is no other options
• manual editing in RA1 has always been considered as buggy and too costly (Please note RM keep editing the docx by hand)

Obliged to render our source code to DOCX

Our options

• RST to DOCX via Pandoc + manual edits
• RST to DOCX via Sphinx
• RST to PDF
• Hacked RST to DOCX via Pandoc

Without breaking the user experience

Sphinx specific features

• intersphinx
• autosectionlabel
• numref
• bibliography
• glossary

Which tradeofs?

Code source changelog

• merge RC1 content in RA1
• switch to list-table everywhere to ease string substitution
• write refs.bib, order the entries and call :cite: everywhere
• clean and include terminology from common
• remove all intersphinx entries (please note that RM is listed refs.bib as GSMA PRD NG.126)
• remove all :numref: via appropriate sentences

Special thanks to Cédric, Ildiko, Karine & Pankaj

togsma.py

• create both references and bibliography tables by reading refs.bib
• dump all RST files into a single temp RST file
• replace all :cite: by numerical indexes + targets
• replace all :ref: by implicit hyperlink targets by reading build/objects.inv

Please see togsma.py

tips

• merging in a single file would fail if titles are duplicated
• string subtitution could break tables
• the multiline string subtitution may quickly fail
• the pdf builds also highlight warnings
• docx could be easily corrupted (hard to debug)
• etc.

Fix any RST warning and line wrapping first

demo

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

on gsma side

• to format table in the generated DOCX (1 click per table)
• to make diff between old and new DOCX
• submit DOCX diff to GSMA portal

That’s all folks