Currently Online

Latest Posts

Changes in Documentation Rules

Revision Differences of Revision 15

[TOC] ¶

# Introduction ¶

Our [lua documentation](https://www.widelands.org/documentation/index.html) is build with the [Sphinx-doc Documentation creator](https://www.sphinx-doc.org/en/master/index.html). You might have noticed that the documentation has some chapters containing the word "python". This is due Sphinx-doc is mainly used to document python projects, but there is no Lua documentation creator out there so we use Sphinx-doc with some difficulties. This article covers how it works, some styling rules and some examples for easy copy and paste. ¶

## Build the documentation locally ¶

We encourage to build the documentation locally when you want to work on the documentation and check the made changes locally before proposing them. ¶

The prerequisites for building the documentation locally are: ¶

* python, at least version 3.6 ¶
* [sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html) ¶
* the source code of widelands, see [[ DownloadPage/#development-version | Development version]] ¶

To build the documentation see the file README in the subfolder _"doc/sphinx"_ of the widelands source code. ¶

Locally created documentation looks different (does not have the same style) as on the homepage. ¶

# How it works ¶

Basically creating the documentation is done in three steps: ¶

1. Creating/modifying [[ Documentation Rules/#rst-comments | RST-Comments ]] in the source code ¶
2. Extract this comments by running [[ Documentation Rules/#extract_rstpy | extract_rst.py ]] ¶
3. Let Sphinx-doc make the documentation ¶

The main thing for developers is to create sufficient [[ Documentation Rules/#rst-comments | RST-Comments ]]. ¶

## RST Comments ¶

RST stands for _restructered text_, a markup language. Depending on the file type the comments are for files of type C++ ¶

~~~~ ¶
/* RST ¶
Every ¶
line ¶
will be an RST comment until comment end ¶
*/ ¶
~~~~ ¶
Everything between `/* RST` and `*/` will be extracted by extract_rst.py and added to a corresponding file. ¶

For files of type Lua: ¶

~~~~ ¶
-- RST ¶
-- This is ¶
-- a block of ¶
-- RST comment ¶
-- ¶

-- This comment does not belong to the RST comment (one empty line between comment blocks) ¶
~~~~ ¶
Every comment block starting with `-- RST` will be extracted by extract_rst.py and added to a corresponding file. ¶

For more about the used markup language see: [[ Documentation%20Rules/#restructered-text | Restructered text ]] ¶

## extract_rst.py ¶

This script gathers [[ Documentation Rules/#rst-comments | RST-Comments ]] from different locations and stores them as files in _"doc/sphinx/source"_. It creates/adds also some entries to the documentation tocs. ¶

TODO: When to modify this script (new files, ....) ¶

# Restructered Text ¶

If you are looking at our documentation, e.g. [wl.game](/documentation/autogen_wl_game), you will find a link called _"Show Source"_ in the left sidebar. Clicking this link will show you the restructered text markup which shows the [[ Documentation Rules/#rst-comments | RST Comments ]], of course without the comment markers (`/* RST` .. `/*`, `-- RST`... `--`). Comparing this page with the rendered content will give you a feeling for restrucetred text. ¶

The following paragraphs points out some typical failures when using restructered text for widelands. ¶

For a more detailed description of the markup of restructered text see: [Sphinx restructered text primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) ¶

## Heading markup matters ¶

Sections have an additional line of punctuation characters. Be sure that this additional line is at least as long as the section header: ¶

~~~~ ¶
Section Header ¶
=========== # wrong: Line is too short ¶
~~~~ ¶

See [Sections](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html/#sections) for more about sections. ¶

## Indentation matters ¶

All lines of the same paragraph must be left-aligned to the same level of indentation. Keep an eye on this for _ripped_ documentation e.g. documenting a class with attributes: ¶

~~~~ ¶
/* RST ¶
.. class:: Foo ¶

Desciption of class ¶
over multiple lines ¶
*/ ¶

Lines of C++ Code defining the class ¶

/* RST ¶
.. attribue:: bar # wrong indentation for attribute bar of class Foo ¶

Description of bar ¶

.. attribue:: bar # correct indentation ¶

Description of bar ¶
*/ ¶

Lines of C++ code defining the attribute ¶
~~~~ ¶

# Formatting rules ¶

Most formatting is done automatically by Sphinx-doc. If you want to use formatting in plain text, use this markup: ¶

Formatting | markup | alternative markup
------------------------------------| ----------------------------------------- | ----------------------------
`constants` | `` :const:`true` `` | ``` ``true`` ```
`"string constants"` | `` :const:`"empire-soldier"` ``
"string" | "string" ¶



# C&P Examples ¶

## class ¶

## function ¶

## codeblock ¶

## images