Latest Posts

Documentation Rules

Introduction

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:

  1. Creating/modifying RST-Comments in the source code
  2. Extract these comments by running extract_rst.py
  3. Let Sphinx-doc make the documentation

The main thing for developers is to create sufficient 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: ReStructured Text

extract_rst.py

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, …)

ReStructured Text

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 .. /*, -- 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.

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

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
:class:`~wl.game.Player` Player Using the tilde (~) let the link appear only with ClassName
:meth:`send_to_inbox` send_to_inbox() Parenthesis are added automatically
:attr:`wl.game.Objective.name` wl.game.Objective.name
:attr:`~wl.game.Objective.name` name Using the tilde (~) let the link appear only with the attributes name
:class:`players <wl.game.Player>` players Giving the link another name
`external link <URL>`_ external link Note the trailing underscore after the last apostrophe
:doc:`autogen_auxiliary_coroutine` 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:

  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
--