Our Lua documentation is built with the Sphinx-doc Documentation creator. 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:
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:
- Creating/modifying RST-Comments in the source code
- Extract these comments by running extract_rst.py
- Let Sphinx-doc make the documentation
The main thing for developers is to create sufficient 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 */
/* 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: ReStructured Text
This script gathers 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, …)
If you are looking at our documentation, e.g. 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 RST Comments, of course without the comment markers (
/* 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
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 for more about sections.
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
Most formatting is done automatically by Sphinx-doc. Use this markup for descriptions:
||Don't use spaces inside the code. Otherwise the code will be split:
|Referring to an argument of a function||
||E.g.: The argument plr is the player|
Every class, attribute, method or function can be referenced with the corresponding directive and this markup:
||Player||Using the tilde (~) let the link appear only with ClassName|
||send_to_inbox()||Parenthesis are added automatically|
||name||Using the tilde (~) let the link appear only with the attributes name|
||players||Giving the link another name|
||external link||Note the trailing underscore after the last apostrophe|
||coroutine.lua||Links to a file of the documentation, the label will be the first section. For an alternative see below.|
Alternative for linking to a file:
- Add a directive to the file you want to link to: e.g.
- Referencing is done by
:ref:`richtext.lua`. Note that the leading underscore is omitted.
/* RST .. class:: Player Child of: :class:`wl.bases.PlayerBase` Description of class */
For files of type C++. Note the indentation:
/* RST .. attribute:: inbox (RO) Description of attribute */
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: */
-- 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 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 -- -- 2. Code block follows after the two colons and a blank line:: -- -- local a = "Hello" --
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 --