Documentation Format

The mangos-zero documentation uses reStructuredText as its markup language and Sphinx for building the output (HTML, PDF, ...).

reStructuredText

reStructuredText “is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system”.

You can learn more about its syntax by reading existing mangos-zero documents or by reading the reStructuredText Primer on the Sphinx website.

If you are familiar with Markdown, be careful as things are sometimes very similar but different:

  • Lists starts at the beginning of a line (no indentation is allowed);
  • Inline code blocks use double-ticks (``like this``).

Sphinx

Sphinx is a build system that adds some nice tools to create documentation from reStructuredText documents. As such, it adds new directives and interpreted text roles to standard reST markup.

Syntax Highlighting

All code examples uses C++ as the default highlighted language. You can change it with the code-block directive:

.. code-block:: text

    ############################################
    # MaNGOS realmd configuration file         #
    ############################################

    [RealmdConf]
    ConfVersion=2010062001

Note

A list of supported languages is available on the Pygments website.

Configuration Blocks

Whenever you show a configuration, you must use the code-block directive to show the configuration Text only format.

.. code-block:: text

    ############################################
    # MaNGOS realmd configuration file         #
    ############################################

    [RealmdConf]
    ConfVersion=2010062001

The previous reST snippet renders as follow:

############################################
# MaNGOS realmd configuration file         #
############################################

[RealmdConf]
ConfVersion=2010062001

The current list of supported formats are the following:

Markup format Displayed
cpp C++
sql SQL Statements
text Text Only

Testing Documentation

To test documentation before a commit: