Contributing to Evennia Docs¶
The creation of docs pages is still WIP and we are still figuring things out here and there.
Contributing to the docs is is like contributing to the rest of Evennia: Check out the branch of Evennia you want to edit the documentation for. Create your
own work-branch, make your changes to files in
evennia/docs/source/ and make a PR for it!
The documentation source files are
*.md (Markdown) files found in
Markdown files are simple text files that can be edited with a normal text editor. They can also
contain raw HTML directives (but that is very rarely needed). They primarly use
the Markdown syntax. See the syntax section below for more help.
Source file structure¶
For v 0.9.5, the sources are all together under
evennia/docs/source/. The main files are all
Other files and folders:
source/api/contains the auto-generated API documentation as
.rstfiles. Don’t edit these files manually, your changes will be lost. To refer to these files, use
api:followed by the Python path, for example
source/_staticshould not be modified unless adding a new doc-page feature or changing the look of the HTML documentation.
conf.pyholds the Sphinx configuration. It should usually not be modified except to update the Evennia version on a new branch.
Building the docs locally¶
The sources in
evennia/docs/source/ are built into a documentation using the
Sphinx static generator system. To do this locally you need to use a
make (Linux/Unix/Mac or Windows-WSL). Lacking
that, you could in principle also run the sphinx build-commands manually - read
evennia/docs/Makefile to see which commands are run by the
referred to in this document.
You don’t necessarily have to build the docs locally to contribute. Markdown is not hard and is very readable on its raw text-form.
You can furthermore get a good feel for how things will look using a Markdown-viewer like Grip. Editors like ReText or IDE’s like PyCharm also have native Markdown previews. Building the docs locally is however the only way to make sure the outcome is exactly as you expect. The process will also find any mistakes you made, like making a typo in a link.
Building only the main documentation¶
This is the fastest way to compile and view your changes. It will only build the main documentation pages and not the API auto-docs or versions. All is done in your terminal/console.
(Optional, but recommended): Activate a virtualenv with Python 3.7.
cdto into the
Install the documentation-build requirements:
make install or pip install -r requirements.txt
Next, build the html-based documentation (re-run this in the future to build your changes):
Note any errors from files you have edited.
The html-based documentation will appear in the new folder
Use a web browser to open
file://<path-to-folder>/evennia/docs/build/html/index.htmland view the docs. Note that you will get errors if clicking a link to the auto-docs, because you didn’t build them!
Building the main documentation and API docs¶
The full documentation includes both the doc pages and the API documentation generated from the Evennia source. For this you must install Evennia and initialize a new game with a default database (you don’t need to have any server running)
It’s recommended that you use a virtualenv. Install your cloned version of Evennia into by pointing to the repo folder (the one containing
pip install -e evennia
Make sure you are in the parent folder containing your
evennia/repo (so two levels up from
Create a new game folder called exactly
gamedirat the same level as your
evennia --init gamedir
cdinto it and create a new, empty database. You don’t need to start the game or do any further changes after this.
This is how the structure should look at this point:
(top) | ----- evennia/ (the top-level folder, containing docs/) | ----- gamedir/
(If you are already working on a game, you may of course have your ‘real’ game folder there as well. We won’t touch that.)
evennia/docs/and install the doc-building requirements (you only need to do this once):
make install or pip install -r requirements.txt
Finally, build the full documentation, including the auto-docs:
The rendered files will appear in a new folder
evennia/docs/build/html/. Note any errors from files you have edited.
Point your web browser to
file://<path-to-folder>/evennia/docs/build/html/index.htmlto view the full docs.
Building with another gamedir¶
If you for some reason want to use another location of your
gamedir/, or want it
named something else (maybe you already use the name ‘gamedir’ for your development …),
you can do so by setting the
EVGAMEDIR environment variable to the absolute path
of your alternative game dir. For example (bash):
EVGAMEDIR=/my/path/to/mygamedir make local
Building for release¶
The full Evennia documentation contains docs from many Evennia versions, old and new. This is done by pulling documentation from Evennia’s old release branches and building them all so readers can choose which one to view. Only specific official Evennia branches will be built, so you can’t use this to build your own testing branch.
All local changes must have been committed to git first, since the versioned docs are built by looking at the git tree.
To build for local checking, run (
mvstands for “multi-version”):
This is as close to the ‘real’ version of the docs as you can get locally. The different versions
will be found under
evennia/docs/build/versions/. During deploy a symlink
latest will point
to the latest version of the docs.
Releasing the official docs requires git-push access the the Evennia
github. So there is no risk of you releasing your local changes accidentally.
To deploy docs in two steps
make mv-local make deploy
If you know what you are doing you can also do build + deploy in one step:
After deployment finishes, the updated live documentation will be available at https://evennia.github.io/evennia/latest/.
The format used for Evennia’s docs is Markdown (Commonmark). While markdown supports a few alternative forms for some of these, we try to stick to the below forms for consistency.
We generally use underscores for italics and double-asterisks for bold:
_Italic text_- Italic text
**Bold Text**- Bold text
# to indicate sections/headings. The more
# the more of a sub-heading it is (will get
smaller and smaller font).
Don’t use the same heading/subheading name more than once in one page. While Markdown does not prevent it, it will make it impossible to refer to that heading uniquely. The Evennia documentation preparser will detect this and give you an error.
One can create both bullet-point lists and numbered lists:
- first bulletpoint - second bulletpoint - third bulletpoint
1. Numbered point one 2. Numbered point two 3. Numbered point three
Numbered point one
Numbered point two
Numbered point three
A blockquote will create an indented block. It’s useful for emphasis and is
added by starting one or more lines with
>. For ‘notes’ you can also use
an explicit Note.
> This is an important > thing to remember.
Note: This is an important thing to remember.
It’s common to want to mark something to be displayed verbatim - just as written - without any
Markdown parsing. In running text, this is done using backticks (`), like `verbatim text` becomes
If you want to put the verbatim text on its own line, you can do so easily by simply indenting it 4 spaces (add empty lines on each side for readability too):
This is normal text This is verbatim text This is normal text
Another way is to use triple-backticks:
``` Everything within these backticks will be verbatim. ```
A special case is code examples - we want them to get code-highlighting for readability. This is done by using the triple-backticks and specify which language we use:
```python def a_python_func(x): return x * x ```
1 2 3
def a_python_func(x): return x * x
Markdown is easy to read and use. But while it does most of what we need, there are some things it’s
not quite as expressive as it needs to be. For this we need to fall back to the ReST markup
language which the documentation system uses under the hood. This is done by specifying
as the name of the
language of a literal block:
```eval_rst This will be evaluated as ReST. All content must be indented. ```
There is also a short-hand form for starting a ReST directive without need for
```directive:: possible-option Content *must* be indented for it to be included in the directive. New lines are ignored, empty lines starts a new paragraph. ```
Within a ReST block, one must use Restructured Text syntax, which is not the same as Markdown.
Single backticks around text makes it italic.
Double backticks around text makes it
A link is written within back-ticks, with an underscore at the end:
Below are examples of ReST-block structures.
This kind of note may pop more than doing a
> Note: .... Contrary to a
blockquote, the end result will not be indented.
```note:: Remember that you have to indent this content for it to be part of the note. ```
Remember that you have to indent this content for it to be part of the note.
This is for particularly important and visible notes.
```important:: This is important because it is! ```
This is important because it is!
A warning block is used to draw attention to particularly dangerous things, or features easy to mess up.
```warning:: Be careful about this ... ```
Be careful about this …
Version changes and deprecations¶
These will show up as one-line warnings that suggest an added, changed or deprecated feature beginning with particular version.
```versionadded:: 1.0 ```
New in version 1.0.
```versionchanged:: 1.0 How the feature changed with this version. ```
Changed in version 1.0: How the feature changed with this version.
```deprecated:: 1.0 ```
Deprecated since version 1.0.
A table is specified using ReST table syntax (they don’t need to be indented):
```eval_rst ===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== ======= ```
A and B
or the more flexible but verbose
```eval_rst +------------------------+------------+----------+----------+ | Header row, column 3 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | ... | ... | | +------------------------+------------+----------+----------+ ```
Header row, column 3 (header rows optional)
body row 1, column 1
body row 2
A more flexible code block¶
The regular Markdown Python codeblock is usually enough but for more direct control over the style, one
can also specify the code block explicitly in
ReST for more flexibility.
It also provides a link to the code block, identified by its name.
```code-block:: python :linenos: :emphasize-lines: 1-2,8 :caption: An example code block :name: A full code block example from evennia import Command class CmdEcho(Command): """ Usage: echo <arg> """ key = "echo" def func(self): self.caller.msg(self.args.strip()) ```
1 2 3 4 5 6 7 8
from evennia import Command class CmdEcho(Command): """ Usage: echo <arg> """ key = "echo" def func(self): self.caller.msg(self.args.strip())
:linenos: turns on line-numbers and
:emphasize-lines: allows for emphasizing certain lines
in a different color. The
:caption: shows an instructive text and
:name: is used to reference
block through the link that will appear (so it should be unique for a give document).
The default markdown syntax will actually generate a code-block ReST instruction like this automatically for us behind the scenes. But the automatic generation can’t know things like emphasize- lines or captions since that’s not a part of the Markdown specification.
The source code docstrings will be parsed as Markdown. When writing a module docstring, you can use Markdown formatting,
including header levels down to 4th level (
#### SubSubSubHeader). After the module documentation it’s
a good idea to end with four dashes
----. This will create a visible line between the documentation and the
class/function docs to follow. See for example the Traits docs.
All non-private classes, methods and functions must have a Google-style docstring, as per the Evennia coding style guidelines. This will then be correctly formatted into pretty api docs.
Evennia leverages Sphinx with the recommonmark extension, which allows us to write our docs in light-weight Markdown (more specifically CommonMark, like on github) rather than ReST. The recommonmark extension however also allows us to use ReST selectively in the places were it is more expressive than the simpler (but much easier) Markdown.