<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>
<blockquote>
<div><p>Note: Don’t edit the files in <codeclass="docutils literal notranslate"><spanclass="pre">source/api/</span></code>. These are auto-generated and your changes
<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 sources in <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/source/</span></code> are built into a pretty documentation using
the <aclass="reference external"href="https://www.sphinx-doc.org/en/master/">Sphinx</a> static generator system. To do so locally you need to either
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 <codeclass="docutils literal notranslate"><spanclass="pre">make</span></code>.</p>
<p>You don’t necessarily <em>have</em> to build the docs locally to contribute. But
building them allows you to check for yourself that syntax is correct and that
your change comes out looking as you expected.</p>
<p>If you only want to build the main documentation pages (not the API auto-docs),
you don’t need to install Evennia itself, only the documentation resources.
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>The html-based documentation will appear in the 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>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 it
running)</p>
<ul>
<li><p>Follow the normal <aclass="reference internal"href="Getting-Started.html"><spanclass="doc">Evennia Getting-Started instructions</span></a>
to install Evennia into a virtualenv. Get back here once everything is installed but
before creating a new game.</p></li>
<li><p>Make sure you <codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> to the folder <em>containing</em> your <codeclass="docutils literal notranslate"><spanclass="pre">evennia/</span></code> repo (so two 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 game
<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>Make sure you are still in your virtualenv, then go to <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/</span></code> and
<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
<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 as you can get locally. The different versions
will be found under <codeclass="docutils literal notranslate"><spanclass="pre">evennia/docs/build</span></code>. During deploy a symlink <codeclass="docutils literal notranslate"><spanclass="pre">latest</span></code> will point
<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>
<h1>Editing syntax<aclass="headerlink"href="#editing-syntax"title="Permalink to this headline">¶</a></h1>
<p>The format used for Evennia’s docs is <aclass="reference external"href="https://commonmark.org/help/">Markdown</a> (Commonmark). While markdown supports a
few alternative forms for some of these, we try to stick to the below forms for consistency.</p>
<divclass="section"id="italic-bold">
<h2>Italic/Bold<aclass="headerlink"href="#italic-bold"title="Permalink to this headline">¶</a></h2>
<p>We generally use underscores for italics and double-asterisks for bold:</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 smaller
<h2>Notes<aclass="headerlink"href="#notes"title="Permalink to this headline">¶</a></h2>
<p>A note can be used to enphasise important things. It’s added by starting one or more lines with <codeclass="docutils literal notranslate"><spanclass="pre">></span></code>.</p>
<h2>Links<aclass="headerlink"href="#links"title="Permalink to this headline">¶</a></h2>
<ulclass="simple">
<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>
</ul>
<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>.</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 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 the
<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">issue</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">bug-report</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">feature-request</span></code> - links to the same github issue select page.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span> If you find a problem, make a [bug report](issue)!
</pre></div>
</div>
<p>This will generate a link to https://github.com/evennia/evennia/issues/new/choose.</p>
</li>
</ul>
<blockquote>
<div><p>For some reason these particular shortcuts gives a warning during documentation compilation. This
can be ignored.</p>
</div></blockquote>
</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 <codeclass="docutils literal notranslate"><spanclass="pre">verbatim</span><spanclass="pre">text</span></code>.</p>
<p>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):</p>
<h2>ReST blocks<aclass="headerlink"href="#rest-blocks"title="Permalink to this headline">¶</a></h2>
<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 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 <codeclass="docutils literal notranslate"><spanclass="pre">eval_rst</span></code>:</p>
Content that *must* be indented for it to be included in the directive.
New lines are ignored except if separated by an empty line.
```
</pre></div>
</div>
<p>See below for examples of this.</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 even more than a normal <codeclass="docutils literal notranslate"><spanclass="pre">></span><spanclass="pre">note</span></code>. It may however also make the test
<h3>Tables<aclass="headerlink"href="#tables"title="Permalink to this headline">¶</a></h3>
<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>:</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. The automatic generation can’t know things like emphasize-lines
or caption since that’s not a part of the Markdown specification.</p>
</div></blockquote>
</div>
</div>
</div>
<divclass="section"id="technical">
<h1>Technical<aclass="headerlink"href="#technical"title="Permalink to this headline">¶</a></h1>
<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 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 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.</p>
<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> extension
to understand our friendly Google-style docstrings used in classes and functions etc.</p>
