Changes in Documentation Rules
Revision Differences of Revision 6
[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 contains the word "python", this is due Sphinx-doc is mainly used to document python projects, but there is no Lua documentation creator 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 ¶
¶
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. ¶
¶
## 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 ¶
¶
## RST Comments ¶
¶
RST stands for _restructered text_. 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 does not belong to the RST comment (one empty line between comment block) ¶
~~~~ ¶
Every comment block starting `--RST` will be extracted by extract_rst.py and added to a corresponding file. ¶
¶
### Indentation matters ¶
¶
## Formatting rules ¶
¶
¶
## Examples