<p>Contributing to the docs is is like <aclass="reference internal"href="Contributing.html"><spanclass="doc">contributing to the rest of Evennia</span></a>: Check out the branch of Evennia you want to edit the documentation for. Create your
own work-branch, make your changes to files in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code> and make a PR for it!</p>
<p>The documentation source files are <codeclass="docutils literal notranslate"><spanclass="pre">*.md</span></code> (Markdown) files found in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code>.
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 <aclass="reference external"href="https://spec.commonmark.org/current/">Markdown</a> syntax. See <aclass="reference external"href="#Editing-syntax">the syntax section below</a> for more help.</p>
<p>For v 0.9.5, the sources are all together under <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code>. The main files are all
<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">.rst</span></code> files. Don’t edit these
files manually, your changes will be lost. To refer to these files, use <codeclass="docutils literal notranslate"><spanclass="pre">api:</span></code> followed by
the Python path, for example <codeclass="docutils literal notranslate"><spanclass="pre">[rpsystem</span><spanclass="pre">contrib](api:evennia.contrib.rpsystem)</span></code>.</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> should not be modified unless adding a new doc-page
feature or changing the look of the HTML documentation.</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
<h2>Building the docs locally<aclass="headerlink"href="#building-the-docs-locally"title="Permalink to this headline">¶</a></h2>
<p>The sources in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code> are built into a documentation using the
<aclass="reference external"href="https://www.sphinx-doc.org/en/master/">Sphinx</a> static generator system. 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>
<p>You don’t necessarily <em>have</em> to build the docs locally to contribute. Markdown is
not hard and is very readable on its raw text-form.</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. Building the docs locally is
<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.7.</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>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
<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>
<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
<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
<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
<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>
<divclass="section"id="release">
<h4>Release<aclass="headerlink"href="#release"title="Permalink to this headline">¶</a></h4>
<p>Releasing the official docs requires git-push access the the Evennia <codeclass="docutils literal notranslate"><spanclass="pre">gh-pages</span></code> branch
on <codeclass="docutils literal notranslate"><spanclass="pre">github</span></code>. So there is no risk of you releasing your local changes accidentally.</p>
<h2>Headings<aclass="headerlink"href="#headings"title="Permalink to this headline">¶</a></h2>
<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
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">[linktext](url_or_ref)</span></code> - gives a clickable link <aclass="reference external"href="#Links">linktext</a>.</p></li>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">url_or_ref</span></code> can either be a full <codeclass="docutils literal notranslate"><spanclass="pre">http://...</span></code> url or an internal <em>reference</em>. For example, use
<codeclass="docutils literal notranslate"><spanclass="pre">[my</span><spanclass="pre">document](My-Document)</span></code> to link to the document <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/My-Document.md</span></code>. Avoid
using
full <codeclass="docutils literal notranslate"><spanclass="pre">http://</span></code> linking unless really referring to an external resource.</p>
<p>You can point to sub-sections (headings) in a document by using a single <codeclass="docutils literal notranslate"><spanclass="pre">#</span></code> and the name of the
heading, replacing spaces with dashes. So to refer to a heading <codeclass="docutils literal notranslate"><spanclass="pre">##</span><spanclass="pre">Cool</span><spanclass="pre">Stuff</span></code> inside <codeclass="docutils literal notranslate"><spanclass="pre">My-Document</span></code>
would be a link <codeclass="docutils literal notranslate"><spanclass="pre">[cool</span><spanclass="pre">stuff](My-Document#Cool-Stuff)</span></code>. This is why headings must be uniquely named
within on document.</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">[linktext][linkref]</span></code> - refer to a reference defined later in the document.</p></li>
</ul>
<p>Urls can get long and if you are using the same url 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
and 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>
<h3>Special references<aclass="headerlink"href="#special-references"title="Permalink to this headline">¶</a></h3>
<p>The Evennia documentation supports some special reference shortcuts in links:</p>
<divclass="section"id="github-online-repository">
<h4>Github online repository<aclass="headerlink"href="#github-online-repository"title="Permalink to this headline">¶</a></h4>
<ul>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">github:</span></code> - a shortcut for the full path to the Evennia repository on github. This must be given
with forward-slashes and include the <codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> file ending. It will refer to the <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code> branch by default:</p>
<p>This will remap to https://github.com/evennia/evennia/blob/master/evennia/objects/objects.py.</p>
</li>
<li><p>To refer to the <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branch, start the url with <codeclass="docutils literal notranslate"><spanclass="pre">develop/</span></code>:</p>
<h4>API<aclass="headerlink"href="#api"title="Permalink to this headline">¶</a></h4>
<ul>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">api:</span></code> - references a path in the api documentation. This is specified as a Python-path:</p>
<p>This will create a link to the auto-generated <codeclass="docutils literal notranslate"><spanclass="pre">evennia/source/api/evennia.objects.rst</span></code> document.</p>
<p>Since api-docs are generated alongside the documentation, this will always be the api docs for
<h4>Bug reports/feature request<aclass="headerlink"href="#bug-reports-feature-request"title="Permalink to this headline">¶</a></h4>
<ul>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">github:issue</span></code> - links to the github issue selection page, where the user can choose which type of
issue to create.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span> If you find a problem, make a [bug report](github:issue)!
</pre></div>
</div>
<p>This will generate a link to https://github.com/evennia/evennia/issues/new/choose.</p>
</li>
</ul>
</div>
</div>
</div>
<divclass="section"id="verbatim-text">
<h2>Verbatim text<aclass="headerlink"href="#verbatim-text"title="Permalink to this headline">¶</a></h2>
<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
not quite as expressive as it needs to be. For this we need to fall back to the <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">ReST</a> markup
language which the documentation system uses under the hood. This is done by specifying <codeclass="docutils literal notranslate"><spanclass="pre">eval_rst</span></code>
as the name of the <codeclass="docutils literal notranslate"><spanclass="pre">language</span></code> of a literal block:</p>
<p>There is also a short-hand form for starting a <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restruturedtext/directives.html">ReST directive</a> without need for
<p><aclass="reference external"href="https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html">Here is a ReST formatting cheat sheet</a>.</p>
<p>Below are examples of ReST-block structures.</p>
<divclass="section"id="note">
<h3>Note<aclass="headerlink"href="#note"title="Permalink to this headline">¶</a></h3>
<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>. Contrary to a
<aclass="reference external"href="#Blockquotes">blockquote</a>, the end result will not be indented.</p>
<p>A table is specified using <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables">ReST table syntax</a> (they don’t need to be indented):</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 give document).</p>
<blockquote>
<div><p>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.</p>
</div></blockquote>
</div>
</div>
<divclass="section"id="code-documentation">
<h2>Code documentation<aclass="headerlink"href="#code-documentation"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>). 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 external"href="api/evennia.contrib.traits.html">the Traits docs</a>.</p>
<p>All non-private classes, methods and functions must have a Google-style docstring, as per the
<aclass="reference external"href="https://github.com/evennia/evennia/blob/master/evennia/CODING_STYLE.md">Evennia coding style guidelines</a>. This will then be correctly formatted
<p>Evennia leverages <aclass="reference external"href="https://www.sphinx-doc.org/en/master/">Sphinx</a> with the <aclass="reference external"href="https://recommonmark.readthedocs.io/en/latest/index.html">recommonmark</a> extension, which allows us
docs in light-weight Markdown (more specifically <aclass="reference external"href="https://spec.commonmark.org/current/">CommonMark</a>, like on github) rather
<p>For <aclass="reference external"href="http://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="http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html">napoleon</a>
