Benefits

  • There will be an online version for all released game versions

  • It will be shipped with the game (can be viewed from within the game even)

  • The information will always fit to the game version installed.

  • changelog can be integrated and can cross-reference to features and documentation

  • internal / external parts can be split

  • Automatic c++ code documentation

  • Completeness-checks possible (I.e. is every lua function documented here?)

  • Themes

  • multiple output formats: PDF, epub, etc (click on “read the docs” in the lower left corner)

  • lots of useful Extensions (see there: http://sphinxext-survey.readthedocs.io/en/latest/ , http://www.sphinx-doc.org/en/stable/develop.html)

  • Cross-language documentation: document design, lua, c++ and everything else in one central documentation

  • Helper: Convert mediawiki to RST: https://pandoc.org/try/?text=&from=mediawiki&to=

  • Community can still edit the public part: via public github project

  • Documentation could documenting itself via commit logs

  • It supports math:

    \[\begin{split}\lim_{x\to 0}{\frac{e^x-1}{2x}} \overset{\left[\frac{0}{0}\right]}{\underset{\mathrm{H}}{=}} \lim_{x\to 0}{\frac{e^x}{2}}={\frac{1}{2}} &=12+7 \int_0^2 \left( -\frac{1}{4}\left(e^{-4t_1}+e^{4t_1-8}\right) \right)\,dt_1\ \\ &= 12-\frac{7}{4}\int_0^2 \left( e^{-4t_1}+e^{4t_1-8} \right)\,dt_1\\\end{split}\]
  • Live edit and preview in VS Code: https://github.com/vscode-restructuredtext/vscode-restructuredtext

  • ‘edit on gitlab’ Button in top-right corner: edit via your browser.

  • build locally via make.bat and installed python

  • updates website http://documentation/ upon push in under a minute

  • integrated search, table of content and glossary

  • Ability to add cross reference across languages:

    • C++ Class: ColorI (:cpp:class:`ColorI`)
    • C++ member: ColorI::red (:cpp:member:`ColorI::red`)
    • C++ function: ColorI::__tostring() (:cpp:func:`ColorI::__tostring`)
  • graphviz integration:

    digraph Flatland {

   a -> b -> c -> g;
   a  [shape=polygon,sides=4]
   b  [shape=polygon,sides=5]
   c  [shape=polygon,sides=6]

   g [peripheries=3,color=yellow];
   s [shape=invtriangle,peripheries=1,color=red,style=filled];
   w  [shape=triangle,peripheries=1,color=blue,style=filled];

   }