<h1>Contributing to Evennia Docs<aclass="headerlink"href="#contributing-to-evennia-docs"title="Permalink to this headline">¶</a></h1>
<asideclass="sidebar">
<pclass="sidebar-title">Building the docs locally?</p>
<p>You do <em>not</em> 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 <aclass="reference internal"href="#building-the-docs-locally"><spanclass="std std-doc">at the end of this document</span></a>.</p>
</aside>
<ulclass="simple">
<li><p>You can contribute to docs by creating a <aclass="reference external"href="https://github.com/evennia/evennia/issues/new/choose">Documentation issue</a>.</p></li>
<li><p>You can contribute to docs by making a <aclass="reference internal"href="Contributing.html"><spanclass="doc std std-doc">PR</span></a> like for any other code. The sources are found in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code>.</p></li>
</ul>
<p>The documentation source files are <codeclass="docutils literal notranslate"><spanclass="pre">*.md</span></code> (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 <aclass="reference external"href="https://spec.commonmark.org/current/">Markdown</a> syntax with <aclass="reference external"href="https://myst-parser.readthedocs.io/en/latest/syntax/reference.html">MyST extensions</a>.</p>
<sectionid="source-file-structure">
<h2>Source file structure<aclass="headerlink"href="#source-file-structure"title="Permalink to this headline">¶</a></h2>
<p>The sources are organized into several rough categories, with only a few administrative documents
at the root of <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code>.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/Components/</span></code> are docs describing separate Evennia building blocks, that is, things
that you can import and use. This extends and elaborates on what can be found out by reading the api docs themselves. Example are documentation for <codeclass="docutils literal notranslate"><spanclass="pre">Accounts</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">Objects</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Commands</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/Concepts/</span></code> describes how larger-scale features of Evennia hang together - things that can’t easily be broken down into one isolated component. This can be general descriptions of how Models and Typeclasses interact to the path a message takes from the client to the server and back.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/Setup/</span></code> holds detailed docs on installing, running and maintaining the Evennia server and the infrastructure around it.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/Coding/</span></code> has help on how to interact with, use and navigate the Evennia codebase itself. This also has non-Evennia-specific help on general development concepts and how to set up a sane development environment.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/Contribs/</span></code> holds documentation specifically for packages in the <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contribs/</span></code> folder. Any contrib-specific tutorials will be found here instead of in <codeclass="docutils literal notranslate"><spanclass="pre">Howtos</span></code></p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/Howtos/</span></code> holds docs that describe how to achieve a specific goal, effect or
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/Howtos/Beginner-Tutorial/</span></code> holds all documents part of the initial tutorial sequence.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/api/</span></code> contains the auto-generated API documentation as <codeclass="docutils literal notranslate"><spanclass="pre">.html</span></code> files. Don’t edit these files manually, they are auto-generated from sources.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">source/_templates</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">source/_static</span></code> hold files for the doc itself. They should only be modified if wanting to change the look and structure of the documentation generation itself.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">conf.py</span></code> holds the Sphinx configuration. It should usually not be modified except to update the Evennia version on a new branch.</p></li>
<h3>Headings<aclass="headerlink"href="#headings"title="Permalink to this headline">¶</a></h3>
<p>We use <codeclass="docutils literal notranslate"><spanclass="pre">#</span></code> to indicate sections/headings. The more <codeclass="docutils literal notranslate"><spanclass="pre">#</span></code> the more of a sub-heading it is (will get smaller and smaller font).</p>
<div><p>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.</p>
</div></blockquote>
</section>
<sectionid="lists">
<h3>Lists<aclass="headerlink"href="#lists"title="Permalink to this headline">¶</a></h3>
<p>One can create both bullet-point lists and numbered lists:</p>
<h3>Links<aclass="headerlink"href="#links"title="Permalink to this headline">¶</a></h3>
<p>The link syntax is <codeclass="docutils literal notranslate"><spanclass="pre">[linktext](url_or_ref)</span></code> - this gives a clickable link <aclass="reference internal"href="#links"><spanclass="std std-doc">linktext</span></a>.</p>
<sectionid="internal-links">
<h4>Internal links<aclass="headerlink"href="#internal-links"title="Permalink to this headline">¶</a></h4>
<p>Most links will be to other pages of the documentation or to Evennia’s API docs. Each document
heading can be referenced. The reference always starts with <codeclass="docutils literal notranslate"><spanclass="pre">#</span></code>. The heading-name is always
given in lowercase and ignores any non-letters. Spaces in the heading title are replaced with
a single dash <codeclass="docutils literal notranslate"><spanclass="pre">-</span></code>.</p>
<p>As an example, let’s assume the following is the contents of a file <codeclass="docutils literal notranslate"><spanclass="pre">Menu-stuff.md</span></code>:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># Menu items</span>
<div><p>It’s fine to not include the <codeclass="docutils literal notranslate"><spanclass="pre">.md</span></code> file ending in the reference. The Evennia doc preparser will correct for this (and also insert any needed relative paths in the reference).</p>
</div></blockquote>
</section>
<sectionid="api-links">
<h4>API links<aclass="headerlink"href="#api-links"title="Permalink to this headline">¶</a></h4>
<p>The documentation contains auto-generated documentation for all of Evennia’s source code. You
can direct the reader to the sources by just giving the python-path to the location of the
resource by just starting with an <codeclass="docutils literal notranslate"><spanclass="pre">evennia.</span></code> prefix:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span> [DefaultObject](evennia.objects.objects.DefaultObject) <- like this!
</pre></div>
</div>
<p><aclass="reference internal"href="api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject"title="evennia.objects.objects.DefaultObject"><spanclass="xref myst py py-class">DefaultObject</span></a><- like this!</p>
<blockquote>
<div><p>Note that you can’t refer to files in the <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> folder this way. The game folder is generated
dynamically and is not part of the api docs. The closest is <codeclass="docutils literal notranslate"><spanclass="pre">evennia.game_template</span></code>, which is what is copied to create the game dir on <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">--init</span></code>.</p>
</div></blockquote>
</section>
<sectionid="external-links">
<h4>External links<aclass="headerlink"href="#external-links"title="Permalink to this headline">¶</a></h4>
<p>These are links to resources outside of the documentation. We also provide some convenient shortcuts</p>
<li><p>By using <codeclass="docutils literal notranslate"><spanclass="pre">(github:evennia/objects/objects.py)</span></code> as link target, you can point to a place on the Evennia github page (main branch).</p></li>
<li><p>Use <codeclass="docutils literal notranslate"><spanclass="pre">(github:issue)</span></code> to point to the github issue-creation page.</p></li>
</ul>
<blockquote>
<div><p>Note that if you want to refer to code, it’s usually better to <aclass="reference internal"href="#api-links"><spanclass="std std-doc">link to the API</span></a> rather than point to github.</p>
</div></blockquote>
</section>
</section>
<sectionid="urls-references-in-one-place">
<h3>Urls/References in one place<aclass="headerlink"href="#urls-references-in-one-place"title="Permalink to this headline">¶</a></h3>
<p>Urls can get long and if you are using the same url/reference in many places it can get a
little cluttered. So you can also put the url as a ‘footnote’ at the end of your document.
You can then refer to it by putting your reference within square brackets <codeclass="docutils literal notranslate"><spanclass="pre">[</span><spanclass="pre">]</span></code>. Here’s an example:</p>
<p>As seen, the Markdown syntax can be pretty sloppy (columns don’t need to line up) as long as you
include the heading separators and make sure to add the correct number of <codeclass="docutils literal notranslate"><spanclass="pre">|</span></code> on every line.</p>
</section>
<sectionid="verbatim-text">
<h3>Verbatim text<aclass="headerlink"href="#verbatim-text"title="Permalink to this headline">¶</a></h3>
<p>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
<p>For examples of using the Python command-line, use <codeclass="docutils literal notranslate"><spanclass="pre">python</span></code> language and <codeclass="docutils literal notranslate"><spanclass="pre">>>></span></code> prompt.</p>
<p>When showing an in-game command, use the <codeclass="docutils literal notranslate"><spanclass="pre">shell</span></code> language type and <codeclass="docutils literal notranslate"><spanclass="pre">></span></code> as the prompt.
<p>For actual shell prompts you can either use <codeclass="docutils literal notranslate"><spanclass="pre">bash</span></code> language type or just indent the line.
Use <codeclass="docutils literal notranslate"><spanclass="pre">$</span></code> for the prompt when wanting to show what is an input and what is an output, otherwise
skip it - it can be confusing to users not that familiar with the command line.</p>
<h3>MyST directives<aclass="headerlink"href="#myst-directives"title="Permalink to this headline">¶</a></h3>
<p>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 use extended <aclass="reference external"href="https://myst-parser.readthedocs.io/en/latest/syntax/reference.html">MyST</a> syntax. This is
<h4>Note<aclass="headerlink"href="#note"title="Permalink to this headline">¶</a></h4>
<p>This kind of note may pop more than doing a <codeclass="docutils literal notranslate"><spanclass="pre">></span><spanclass="pre">Note:</span><spanclass="pre">...</span></code>.</p>
<h4>A more flexible code block<aclass="headerlink"href="#a-more-flexible-code-block"title="Permalink to this headline">¶</a></h4>
<p>The regular Markdown Python codeblock is usually enough but for more direct control over the style, one
can also use the <codeclass="docutils literal notranslate"><spanclass="pre">{code-block}</span></code> directive that takes a set of additional <codeclass="docutils literal notranslate"><spanclass="pre">:options:</span></code>:</p>
<divclass="code-block-caption"><spanclass="caption-text">An example code block</span><aclass="headerlink"href="#a-full-code-block-example"title="Permalink to this code">¶</a></div>
<p>Here, <codeclass="docutils literal notranslate"><spanclass="pre">:linenos:</span></code> turns on line-numbers and <codeclass="docutils literal notranslate"><spanclass="pre">:emphasize-lines:</span></code> allows for emphasizing certain lines
in a different color. The <codeclass="docutils literal notranslate"><spanclass="pre">:caption:</span></code> shows an instructive text and <codeclass="docutils literal notranslate"><spanclass="pre">:name:</span></code> is used to reference
this
block through the link that will appear (so it should be unique for a given document).</p>
</section>
<sectionid="eval-rst-directive">
<h4>eval-rst directive<aclass="headerlink"href="#eval-rst-directive"title="Permalink to this headline">¶</a></h4>
<p>As a last resort, we can also fall back to writing <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">ReST</a> directives directly:</p>
<h2>Writing Code docstrings for autodocs<aclass="headerlink"href="#writing-code-docstrings-for-autodocs"title="Permalink to this headline">¶</a></h2>
<p>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 (<codeclass="docutils literal notranslate"><spanclass="pre">####</span><spanclass="pre">SubSubSubHeader</span></code>).</p>
<p>After the module documentation it’s a good idea to end with four dashes <codeclass="docutils literal notranslate"><spanclass="pre">----</span></code>. This will create a visible line between the documentation and the class/function docs to follow. See for example <aclass="reference internal"href="api/evennia.contrib.rpg.traits.html#evennia-contrib-rpg-traits"><spanclass="std std-ref">the Traits docs</span></a>.</p>
<p>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.</p>
</section>
<sectionid="building-the-docs-locally">
<h2>Building the docs locally<aclass="headerlink"href="#building-the-docs-locally"title="Permalink to this headline">¶</a></h2>
<p>Evennia leverages <aclass="reference external"href="https://www.sphinx-doc.org/en/master/">Sphinx</a> with the <aclass="reference external"href="https://myst-parser.readthedocs.io/en/latest/syntax/reference.html">MyST</a> extension, which allows us to write our docs in light-weight Markdown (more specifically <aclass="reference external"href="https://spec.commonmark.org/current/">CommonMark</a>, like on github) rather than Sphinx’ normal ReST syntax. The <codeclass="docutils literal notranslate"><spanclass="pre">MyST</span></code> parser allows for some extra syntax to make us able to express more complex displays than plain Markdown can.</p>
<p>For <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc">autodoc-generation</a> generation, we use the sphinx-<aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html">napoleon</a> extension to understand our friendly Google-style docstrings used in classes and functions etc.</p>
<p>The sources in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code> are built into a documentation using the Sphinx static generator system together with Evennia-custom <em>pre-parsers</em> (also included in the repo).</p>
<p>To do this locally you need to use a system with <codeclass="docutils literal notranslate"><spanclass="pre">make</span></code> (Linux/Unix/Mac or <aclass="reference external"href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">Windows-WSL</a>). Lacking that, you could in principle also run the sphinx build-commands manually - read the <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/Makefile</span></code> to see which commands are run by the <codeclass="docutils literal notranslate"><spanclass="pre">make</span></code>-commands referred to in this document.</p>
<divclass="admonition important">
<pclass="admonition-title">Important</p>
<p>As mentioned at the top, you don’t <em>have</em> 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.</p>
<p>You can furthermore get a good feel for how things will look using a Markdown-viewer like <aclass="reference external"href="https://github.com/joeyespo/grip">Grip</a>. Editors like <aclass="reference external"href="https://github.com/retext-project/retext">ReText</a> or IDE’s like <aclass="reference external"href="https://www.jetbrains.com/pycharm/">PyCharm</a> also have native Markdown previews.</p>
<p>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.</p>
<h3>Building only the main documentation<aclass="headerlink"href="#building-only-the-main-documentation"title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<ul>
<li><p>(Optional, but recommended): Activate a virtualenv with Python 3.11.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> to into the <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs</span></code> folder.</p></li>
<li><p>Install the documentation-build requirements:</p>
<li><p>Note any errors from files you have edited.</p></li>
<li><p>The html-based documentation will appear in the new folder <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/build/html/</span></code>.</p></li>
<li><p>Use a web browser to open <codeclass="docutils literal notranslate"><spanclass="pre">file://<path-to-folder>/evennia/docs/build/html/index.html</span></code> and view the docs. Note that you will get errors if clicking a link to the auto-docs, because you didn’t build them!</p></li>
<h3>Building the main documentation and API docs<aclass="headerlink"href="#building-the-main-documentation-and-api-docs"title="Permalink to this headline">¶</a></h3>
<p>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)</p>
<ul>
<li><p>It’s recommended that you use a virtualenv. Install your cloned version of Evennia into by pointing to the repo folder (the one containing <codeclass="docutils literal notranslate"><spanclass="pre">/docs</span></code>):</p>
<li><p>Make sure you are in the parent folder <em>containing</em> your <codeclass="docutils literal notranslate"><spanclass="pre">evennia/</span></code> repo (so <em>two</em> levels up from <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/</span></code>).</p></li>
<li><p>Create a new game folder called exactly <codeclass="docutils literal notranslate"><spanclass="pre">gamedir</span></code> at the same level as your <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> repo with</p>
<li><p>Then <codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> into it and create a new, empty database. You don’t need to start the game or do any further changes after this.</p>
<p>(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.)</p>
<ul>
<li><p>Go to <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/</span></code> and install the doc-building requirements (you only need to do this once):</p>
<li><p>The rendered files will appear in a new folder <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/build/html/</span></code>. Note any errors from files you have edited.</p></li>
<li><p>Point your web browser to <codeclass="docutils literal notranslate"><spanclass="pre">file://<path-to-folder>/evennia/docs/build/html/index.html</span></code> to view the full docs.</p></li>
</ul>
<sectionid="building-with-another-gamedir">
<h4>Building with another gamedir<aclass="headerlink"href="#building-with-another-gamedir"title="Permalink to this headline">¶</a></h4>
<p>If you for some reason want to use another location of your <codeclass="docutils literal notranslate"><spanclass="pre">gamedir/</span></code>, or want it named something else (maybe you already use the name ‘gamedir’ for your development …), you can do so by setting the <codeclass="docutils literal notranslate"><spanclass="pre">EVGAMEDIR</span></code> environment variable to the absolute path of your alternative game dir. For example:</p>
<h3>Building multiversion docs<aclass="headerlink"href="#building-multiversion-docs"title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<ul>
<li><p>All local changes must have been committed to git first, since the versioned docs are built by looking at the git tree.</p></li>
<li><p>To build for local checking, run (<codeclass="docutils literal notranslate"><spanclass="pre">mv</span></code> stands for “multi-version”):</p>
<p>This is as close to the ‘real’ version of the docs as you can get locally. The different versions will be found under <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/build/versions/</span></code>. During deploy a symlink <codeclass="docutils literal notranslate"><spanclass="pre">latest</span></code> will point to the latest version of the docs.</p>
