Anuket Project

Convert Anuket specifications to rst

Intro

Anuket specifications are written in GFM (GitHub flavored Markdown) what is a pretty weak markdown language (e.g.: It is not possible to scale images). These documents have three "output formats":

  1. Readthedocs uses recommonmark to convert the documents to rst in compile time. Recommonmark is not supported anymore and should be changed to something else anyways.
  2. GitHub "code view". Here GFM is the default format, but GitHub can render rst also without any problem.
  3. Some of the documents are converted to word document and published by GSMA. Conversion fomr rst would be less difficult than form md

For these reasons we would like to convert the documents from markdown to rst. This page contains information and status progress for this work.

Issues

There are some issues what we need to solve on top of converting the documents.

  • Things to be corrected in markdowns
    • Markdown issues
      • Removal of manual heading numbers
      • Removal of heading numbers from links (replace "[0-9]+\-" with "")
      • Replace raw html to markdown
        • images
        • br-s
        • Image captions ()
        • other <p>-s
        • remove internal references (html anchors)
    • Markdown best praciices
      • remove the ToC-s
    • Things needed for the conversion
      • Add blank lines before lists (like here)
    • Remove the bogometers from the chapters
  • After the rst converison
    • Re-align the table line breaks
    • Move the (n)-s to supertext (if possible)


  • Generate heading during the build
  • fixing of broken intra-document links to GitHub generated anchors. These references/links only work on GitHub, but are broken in the Rtd builds already today
  • consistent use of intra-document linking to auto-generated header anchors without including header numbers


Document responsibles

DocumentResponsibleMarkdown correctionsConversion to rstSeparate buildCorrection of linksLinewrap to 120
RMN/Apr mergeddone, build issues resolved.
RA1DoneDoneDonepull/2856: Done

Done

RA2pr createdpr mergedpr opened by Cédric Ollivier
RI1N/Apr mergeddone

Cédric Ollivier is working on it

RI2Georg KunzN/Apr merged

done


#2965
RC1DoneDonedonedoneAlready wrapped
RC2Cédric OllivierDoneDonedonedoneAlready wrapped
Commonpr createdpr created


All index.rst-s and files outside of subproject scopes