Latest Posts

Changes in Documentation Rules

Revision Differences of Revision 2

[TOC] ¶

## Introduction ¶

Our [lua documentation]( is build with the [Sphinx-doc Documentation creator]( You might have noticed that the documentation has some chapters contains the word "python", this due Sphinx-doc is mainly used to document python projects, but there is no Lua documentation creator we use Sphinx-dco with some difficulties. This article covers the workflow to add Lua documentation, 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]( ¶
* the source code of widelands ¶

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

## ¶

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 and added to a corresponding file. ¶

For files of type Lua: ¶

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

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

## Formatting rules ¶

## Examples