Latest Posts

Changes in Documentation Rules

Revision Differences of Revision 27

[TOC] ¶

# Introduction ¶

Our [Lua documentation](https://www.widelands.org/documentation/index.html) is built 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 to Sphinx-doc being used chiefly 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 these 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 _ReStructured 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 | ReStructured 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, …)* ¶

# ReStructured 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 ReStructured 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 ReStructured Text. ¶

The following paragraphs point out some typical snares and pitfalls when using ReStructured Text for Widelands. ¶

For a more detailed description of the markup of ReStructured Text see: [Sphinx ReStructured 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 ¶

Description of class ¶
over multiple lines ¶
*/ ¶

Lines of C++ Code defining the class ¶

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

Description of bar ¶

.. attribute:: bar # correct indentation ¶

Description of bar ¶
*/ ¶

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

# Formatting rules ¶

Most formatting is done automatically by Sphinx-doc. Use this markup for descriptions: ¶

Formatting | Markup | Alternative Markup | Note/Example ¶
------------------------------------| ----------------------------------------- | ---------------------------- | ---------------- ¶
`constants` | `` :const:`true` `` | ``` ``true`` ``` | ¶
`"string constants"` | `` :const:`"empire_soldier"` `` | | ¶
`code sample` | ``` ``codesample`` ``` | | Don't use spaces inside the code. Otherwise the code will be split: `code` _`sample` ¶
Referring to an argument of a function | `**bold**` | | E.g.: The argument **plr** is the player ¶

# C&P Examples ¶

## References (links) ¶

Every class, attribute, method or function can be referenced with the corresponding directive and this markup: ¶

Markup | Shown as | Note ¶
------------------------------------------|-------------------------------------------------------------------------------------------------------- | ----------------------------------- ¶
``:class:`wl.game.Player` `` | [wl.game.Player](/documentation/autogen_wl_game/#wl.game.Player) | ¶
``:class:`~wl.game.Player` `` | [Player](/documentation/autogen_wl_game/#wl.game.Player) | Using the tilde (~) let the link appear only with ClassName ¶
``:meth:`send_to_inbox` `` | [send_to_inbox()](/documentation/autogen_auxiliary_messages.html#send_to_inbox) | Parenthesis are added automatically ¶
``:attr:`wl.game.Objective.name` `` | [wl.game.Objective.name](/documentation/autogen_wl_game.html#wl.game.Objective.name) | ¶
``:attr:`~wl.game.Objective.name` `` | [name](/documentation/autogen_wl_game.html#wl.game.Objective.name) | Using the tilde (~) let the link appear only with the attributes name ¶
``:class:`players <wl.game.Player>` `` | [players](/documentation/autogen_wl_game/#wl.game.Player) | Giving the link another name ¶
`` `external link <URL>`_`` | [external link](/Documentation%20Rules/) | Note the traileading underscore after the last apostrophe ¶
``:doc:`autogen_auxiliary_coroutine` `` | [coroutine.lua](/documentation/autogen_auxiliary_coroutine/) | Links to a file of the documentation, the label will be the first [section](/Documentation%20Rules/#heading-markup-matters). For an alternative see below. ¶

Alternative for linking to a file: ¶

1. Add a directive to the file you want to link to: e.g. `.. _richtext.lua:` ¶
2. Referencing is done by ``:ref:`richtext.lua` ``. Note that the leading underscore is omitted. ¶

## C++ class ¶

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

Child of: :class:`wl.bases.PlayerBase` ¶

Description of class ¶
*/ ¶
~~~~ ¶

## C++ attributes ¶

For files of type C++. Note the indentation: ¶

~~~~ ¶
/* RST ¶
.. attribute:: inbox ¶

(RO) Description of attribute ¶
*/ ¶
~~~~ ¶

## C++ methods ¶

Note the indentation: ¶

~~~~ ¶
/* RST ¶
.. method:: message_box(title, message[, opts]) ¶

Description of method ¶

:arg title: (Each argument has an :arg .....: and a :type ....:.) Description of argument ¶
:type title: :class:`string` ¶

:arg string message: You can omit `:type ....` by using the type directly in the arg-directive :arg type name_of_argument: ¶
*/ ¶
~~~~ ¶

## Lua functions ¶

~~~~ ¶
-- RST ¶
-- .. function:: scroll_to_map_pixel(map_pixel) ¶
-- ¶
-- Description of function ¶
-- ¶
-- :arg map_pixel: pixel to focus on. ¶
-- :type map_pixel: :class:`table` ¶
-- ¶
-- :arg table map_pixel: You can omit `:type ....` by using the type directly in the arg-directive :arg type name_of_argument: ¶
-- ¶
~~~~ ¶

## Code blocks ¶

Code blocks can also be indented. So using a code block for a function looks like (Lua file, indented): ¶

~~~~ ¶
-- ¶
-- .. code-block:: lua ¶
-- ¶
-- function jundlina(title, text) ¶
-- return speech("map:princess.png", "2F9131", title, text) ¶
-- end ¶
-- ¶
~~~~ ¶

Code blocks can also be made with just two colons followed by a blank line, e.g. in a list: ¶

~~~~ ¶
-- ¶
-- 1. Code block follows after the two colons and a blank line:: ¶
-- ¶
-- player_1 = wl.Game().players[1] ¶
-- ¶
-- 2. Code block follows after the two colons and a blank line:: ¶
-- ¶
-- local a = "Hello" ¶
-- ¶
~~~~ ¶

## Images ¶

Images have to be saved below `doc/sphinx/source/images/`. To get an image in the documentation use: ¶

~~~~ ¶
-- ¶
-- .. image:: images/wlrichtext.png ¶
-- :scale: 100 ¶
-- :alt: sample rendering ¶
-- :align: center ¶
-- ¶
~~~~