You do _not_ need to be able to test/build the docs locally to contribute a documentation PR. We'll resolve any issues when we merge and build documentation. If you really want to build the docs for yourself, instructions are [at the end of this document](#building-the-docs-locally).
The documentation source files are `*.md` (Markdown) files. 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 use the [Markdown][commonmark] syntax with [MyST extensions][MyST].
This also has non-Evennia-specific help on general development concepts and how to set up a sane development environment.
-`source/Contribs/` holds documentation specifically for packages in the `evennia/contribs/` folder. Any contrib-specific tutorials will be found here instead of in `Howtos`
-`source/api/` contains the auto-generated API documentation as `.html` files. Don't edit these
files manually, they are auto-generated from sources.
-`source/_templates` and `source/_static` hold files for the doc itself. They should only be modified if wanting to change the look and structure of the documentation generation itself.
> 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 an error.
> It's fine to not include the `.md` file ending in the reference. The Evennia doc preparser will correct for this (and also insert any needed relative paths in the reference).
> Note that you can't refer to files in the `mygame` folder this way. The game folder is generated
dynamically and is not part of the api docs. The closest is `evennia.game_template`, which is what is copied to create the game dir on `evennia --init`.
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](evennia.contrib.rpg.traits).
All non-private classes, methods and functions must have a Google-style docstring, as per the [Evennia coding style guidelines][github:evennia/CODING_STYLE.md]. This will then be correctly formatted into pretty api docs.
Evennia leverages [Sphinx][sphinx] with the [MyST][MyST] extension, which allows us to write our docs in light-weight Markdown (more specifically [CommonMark][commonmark], like on github) rather than Sphinx' normal ReST syntax. The `MyST` parser allows for some extra syntax to make us able to express more complex displays than plain Markdown can.
For [autodoc-generation][sphinx-autodoc] generation, we use the sphinx-[napoleon][sphinx-napoleon] extension to understand our friendly Google-style docstrings used in classes and functions etc.
The sources in `evennia/docs/source/` are built into a documentation using the Sphinx static generator system together with Evennia-custom _pre-parsers_ (also included in the repo).
To do this locally you need to use a system with `make` (Linux/Unix/Mac or [Windows-WSL][Windows-WSL]). Lacking that, you could in principle also run the sphinx build-commands manually - read the `evennia/docs/Makefile` to see which commands are run by the `make`-commands referred to in this document.
As mentioned at the top, you don't _have_ to build the docs locally to contribute. Markdown is not hard and can be written decently without seeing it processed. We can polish it before merging.
You can furthermore get a good feel for how things will look using a Markdown-viewer like [Grip][grip]. Editors like [ReText][retext] or IDE's like [PyCharm][pycharm] also have native Markdown previews.
That said, building the docs locally is the only way to make sure the outcome is exactly as you expect. The processor will also find any mistakes you made, like making a typo in a link.
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.
- The html-based documentation will appear in the new folder `evennia/docs/build/html/`.
- Use a web browser to open `file://<path-to-folder>/evennia/docs/build/html/index.html` and view the docs. Note that you will get errors if clicking a link to the auto-docs, because you didn't build them!
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)
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:
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.
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.
