mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
786 lines
No EOL
54 KiB
HTML
786 lines
No EOL
54 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html>
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>Contributing to Evennia Docs — Evennia 3.x documentation</title>
|
||
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||
<script src="_static/jquery.js"></script>
|
||
<script src="_static/underscore.js"></script>
|
||
<script src="_static/doctools.js"></script>
|
||
<script src="_static/language_data.js"></script>
|
||
<link rel="shortcut icon" href="_static/favicon.ico"/>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="Licensing Q&A" href="Licensing.html" />
|
||
<link rel="prev" title="How To Contribute And Get Help" href="Contributing.html" />
|
||
</head><body>
|
||
|
||
|
||
<div class="admonition important">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
|
||
</div>
|
||
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="Licensing.html" title="Licensing Q&A"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="Contributing.html" title="How To Contribute And Get Help"
|
||
accesskey="P">previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="index.html">Evennia 3.x</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Contributing to Evennia Docs</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
|
||
<div class="documentwrapper">
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<p class="logo"><a href="index.html">
|
||
<img class="logo" src="_static/evennia_logo.png" alt="Logo"/>
|
||
</a></p>
|
||
<div id="searchbox" style="display: none" role="search">
|
||
<h3 id="searchlabel">Quick search</h3>
|
||
<div class="searchformwrapper">
|
||
<form class="search" action="search.html" method="get">
|
||
<input type="text" name="q" aria-labelledby="searchlabel" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
</div>
|
||
<script>$('#searchbox').show(0);</script>
|
||
<h3><a href="index.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Contributing to Evennia Docs</a><ul>
|
||
<li><a class="reference internal" href="#source-file-structure">Source file structure</a></li>
|
||
<li><a class="reference internal" href="#editing-syntax">Editing syntax</a><ul>
|
||
<li><a class="reference internal" href="#italic-bold">Italic/Bold</a></li>
|
||
<li><a class="reference internal" href="#headings">Headings</a></li>
|
||
<li><a class="reference internal" href="#lists">Lists</a></li>
|
||
<li><a class="reference internal" href="#blockquotes">Blockquotes</a></li>
|
||
<li><a class="reference internal" href="#links">Links</a><ul>
|
||
<li><a class="reference internal" href="#internal-links">Internal links</a></li>
|
||
<li><a class="reference internal" href="#api-links">API links</a></li>
|
||
<li><a class="reference internal" href="#external-links">External links</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#urls-references-in-one-place">Urls/References in one place</a></li>
|
||
<li><a class="reference internal" href="#tables">Tables</a></li>
|
||
<li><a class="reference internal" href="#verbatim-text">Verbatim text</a></li>
|
||
<li><a class="reference internal" href="#code-blocks">Code blocks</a></li>
|
||
<li><a class="reference internal" href="#myst-directives">MyST directives</a><ul>
|
||
<li><a class="reference internal" href="#note">Note</a></li>
|
||
<li><a class="reference internal" href="#important">Important</a></li>
|
||
<li><a class="reference internal" href="#warning">Warning</a></li>
|
||
<li><a class="reference internal" href="#version-changes-and-deprecations">Version changes and deprecations</a></li>
|
||
<li><a class="reference internal" href="#sidebar">Sidebar</a></li>
|
||
<li><a class="reference internal" href="#a-more-flexible-code-block">A more flexible code block</a></li>
|
||
<li><a class="reference internal" href="#eval-rst-directive">eval-rst directive</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#writing-code-docstrings-for-autodocs">Writing Code docstrings for autodocs</a></li>
|
||
<li><a class="reference internal" href="#building-the-docs-locally">Building the docs locally</a><ul>
|
||
<li><a class="reference internal" href="#building-only-the-main-documentation">Building only the main documentation</a></li>
|
||
<li><a class="reference internal" href="#building-the-main-documentation-and-api-docs">Building the main documentation and API docs</a><ul>
|
||
<li><a class="reference internal" href="#building-with-another-gamedir">Building with another gamedir</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#building-multiversion-docs">Building multiversion docs</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="Contributing.html"
|
||
title="previous chapter">How To Contribute And Get Help</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="Licensing.html"
|
||
title="next chapter">Licensing Q&A</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<!--h3>This Page</h3-->
|
||
<ul class="this-page-menu">
|
||
<li><a href="_sources/Contributing-Docs.md.txt"
|
||
rel="nofollow">Show Page Source</a></li>
|
||
</ul>
|
||
</div><h3>Links</h3>
|
||
<ul>
|
||
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
|
||
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
|
||
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
|
||
<li><a href="http://games.evennia.com">Game Index</a> </li>
|
||
<li>
|
||
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
|
||
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
|
||
<a href="https://evennia.blogspot.com/">Blog</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section class="tex2jax_ignore mathjax_ignore" id="contributing-to-evennia-docs">
|
||
<h1>Contributing to Evennia Docs<a class="headerlink" href="#contributing-to-evennia-docs" title="Permalink to this headline">¶</a></h1>
|
||
<aside class="sidebar">
|
||
<p class="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 <a class="reference internal" href="#building-the-docs-locally"><span class="std std-doc">at the end of this document</span></a>.</p>
|
||
</aside>
|
||
<ul class="simple">
|
||
<li><p>You can contribute to docs by creating a <a class="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 <a class="reference internal" href="Contributing.html"><span class="doc std std-doc">PR</span></a> like for any other code. The sources are found in <code class="docutils literal notranslate"><span class="pre">evennia/docs/source/</span></code>.</p></li>
|
||
</ul>
|
||
<p>The documentation source files are <code class="docutils literal notranslate"><span class="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 <a class="reference external" href="https://spec.commonmark.org/current/">Markdown</a> syntax with <a class="reference external" href="https://myst-parser.readthedocs.io/en/latest/syntax/reference.html">MyST extensions</a>.</p>
|
||
<section id="source-file-structure">
|
||
<h2>Source file structure<a class="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 <code class="docutils literal notranslate"><span class="pre">evennia/docs/source/</span></code>.</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">Accounts</span></code>, <code class="docutils literal notranslate"><span class="pre">Objects</span></code> and <code class="docutils literal notranslate"><span class="pre">Commands</span></code>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="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><code class="docutils literal notranslate"><span class="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><code class="docutils literal notranslate"><span class="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><code class="docutils literal notranslate"><span class="pre">source/Contribs/</span></code> holds documentation specifically for packages in the <code class="docutils literal notranslate"><span class="pre">evennia/contribs/</span></code> folder. Any contrib-specific tutorials will be found here instead of in <code class="docutils literal notranslate"><span class="pre">Howtos</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">source/Howtos/</span></code> holds docs that describe how to achieve a specific goal, effect or
|
||
result in Evennia. This is often on a tutorial or FAQ form and will refer to the rest of the documentation for further reading.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">source/Howtos/Beginner-Tutorial/</span></code> holds all documents part of the initial tutorial sequence.</p></li>
|
||
</ul>
|
||
<p>Other files and folders:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">source/api/</span></code> contains the auto-generated API documentation as <code class="docutils literal notranslate"><span class="pre">.html</span></code> files. Don’t edit these files manually, they are auto-generated from sources.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">source/_templates</span></code> and <code class="docutils literal notranslate"><span class="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><code class="docutils literal notranslate"><span class="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>
|
||
</ul>
|
||
</section>
|
||
<section id="editing-syntax">
|
||
<h2>Editing syntax<a class="headerlink" href="#editing-syntax" title="Permalink to this headline">¶</a></h2>
|
||
<p>The format used for Evennia’s docs is <a class="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>
|
||
<section id="italic-bold">
|
||
<h3>Italic/Bold<a class="headerlink" href="#italic-bold" title="Permalink to this headline">¶</a></h3>
|
||
<p>We generally use underscores for italics and double-asterisks for bold:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">_Italic</span> <span class="pre">text_</span></code> - <em>Italic text</em></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">**Bold</span> <span class="pre">Text**</span></code> - <strong>Bold text</strong></p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="headings">
|
||
<h3>Headings<a class="headerlink" href="#headings" title="Permalink to this headline">¶</a></h3>
|
||
<p>We use <code class="docutils literal notranslate"><span class="pre">#</span></code> to indicate sections/headings. The more <code class="docutils literal notranslate"><span class="pre">#</span></code> the more of a sub-heading it is (will get smaller and smaller font).</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">Heading</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">##</span> <span class="pre">SubHeading</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">###</span> <span class="pre">SubSubHeading</span></code></p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">####</span> <span class="pre">SubSubSubHeading</span></code></p></li>
|
||
</ul>
|
||
<blockquote>
|
||
<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>
|
||
<section id="lists">
|
||
<h3>Lists<a class="headerlink" href="#lists" title="Permalink to this headline">¶</a></h3>
|
||
<p>One can create both bullet-point lists and numbered lists:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">-</span> <span class="n">first</span> <span class="n">bulletpoint</span>
|
||
<span class="o">-</span> <span class="n">second</span> <span class="n">bulletpoint</span>
|
||
<span class="o">-</span> <span class="n">third</span> <span class="n">bulletpoint</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>first bulletpoint</p></li>
|
||
<li><p>second bulletpoint</p></li>
|
||
<li><p>third bulletpoint</p></li>
|
||
</ul>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mf">1.</span> <span class="n">Numbered</span> <span class="n">point</span> <span class="n">one</span>
|
||
<span class="mf">2.</span> <span class="n">Numbered</span> <span class="n">point</span> <span class="n">two</span>
|
||
<span class="mf">3.</span> <span class="n">Numbered</span> <span class="n">point</span> <span class="n">three</span>
|
||
</pre></div>
|
||
</div>
|
||
<ol class="simple">
|
||
<li><p>Numbered point one</p></li>
|
||
<li><p>Numbered point two</p></li>
|
||
<li><p>Numbered point three</p></li>
|
||
</ol>
|
||
</section>
|
||
<section id="blockquotes">
|
||
<h3>Blockquotes<a class="headerlink" href="#blockquotes" title="Permalink to this headline">¶</a></h3>
|
||
<p>A blockquote will create an indented block. It’s useful for emphasis and is
|
||
added by starting one or more lines with <code class="docutils literal notranslate"><span class="pre">></span></code>. For ‘notes’ you can also use
|
||
an explicit <a class="reference internal" href="#note"><span class="std std-doc">Note</span></a>.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">></span> <span class="n">This</span> <span class="ow">is</span> <span class="n">an</span> <span class="n">important</span>
|
||
<span class="o">></span> <span class="n">thing</span> <span class="n">to</span> <span class="n">remember</span><span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
<blockquote>
|
||
<div><p>Note: This is an important
|
||
thing to remember.</p>
|
||
</div></blockquote>
|
||
</section>
|
||
<section id="links">
|
||
<h3>Links<a class="headerlink" href="#links" title="Permalink to this headline">¶</a></h3>
|
||
<p>The link syntax is <code class="docutils literal notranslate"><span class="pre">[linktext](url_or_ref)</span></code> - this gives a clickable link <a class="reference internal" href="#links"><span class="std std-doc">linktext</span></a>.</p>
|
||
<section id="internal-links">
|
||
<h4>Internal links<a class="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 <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">-</span></code>.</p>
|
||
<p>As an example, let’s assume the following is the contents of a file <code class="docutils literal notranslate"><span class="pre">Menu-stuff.md</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Menu items</span>
|
||
|
||
<span class="n">Some</span> <span class="n">text</span><span class="o">...</span>
|
||
|
||
<span class="c1">## A yes/no? example</span>
|
||
|
||
<span class="n">Some</span> <span class="n">more</span> <span class="n">text</span><span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul>
|
||
<li><p>From <em>inside the same file</em> you can refer to each heading as</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[menus](#menu-items)
|
||
[example](#a-yesno-example)
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>From <em>another file</em>, you reference them as as</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>[menus](Menu-Stuff.md#menu-items)
|
||
[example](Menu-Stuff.md#a-yesno-example)
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<blockquote>
|
||
<div><p>It’s fine to not include the <code class="docutils literal notranslate"><span class="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>
|
||
<section id="api-links">
|
||
<h4>API links<a class="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 <code class="docutils literal notranslate"><span class="pre">evennia.</span></code> prefix:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> [DefaultObject](evennia.objects.objects.DefaultObject) <- like this!
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject" title="evennia.objects.objects.DefaultObject"><span class="xref myst py py-class">DefaultObject</span></a> <- like this!</p>
|
||
<blockquote>
|
||
<div><p>Note that you can’t refer to files in the <code class="docutils literal notranslate"><span class="pre">mygame</span></code> folder this way. The game folder is generated
|
||
dynamically and is not part of the api docs. The closest is <code class="docutils literal notranslate"><span class="pre">evennia.game_template</span></code>, which is what is copied to create the game dir on <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">--init</span></code>.</p>
|
||
</div></blockquote>
|
||
</section>
|
||
<section id="external-links">
|
||
<h4>External links<a class="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>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">evennia</span><span class="o">.</span><span class="n">com</span><span class="p">](</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">evennia</span><span class="o">.</span><span class="n">com</span><span class="p">)</span> <span class="o">-</span> <span class="n">link</span> <span class="n">to</span> <span class="n">an</span> <span class="n">external</span> <span class="n">website</span><span class="o">.</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>By using <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="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 <a class="reference internal" href="#api-links"><span class="std std-doc">link to the API</span></a> rather than point to github.</p>
|
||
</div></blockquote>
|
||
</section>
|
||
</section>
|
||
<section id="urls-references-in-one-place">
|
||
<h3>Urls/References in one place<a class="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 <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">]</span></code>. Here’s an example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="p">[</span><span class="n">clickable</span> <span class="n">link</span><span class="p">][</span><span class="n">mylink</span><span class="p">]</span><span class="o">.</span> <span class="n">This</span> <span class="ow">is</span> <span class="p">[</span><span class="n">another</span> <span class="n">link</span><span class="p">][</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span>
|
||
|
||
<span class="o">...</span>
|
||
|
||
|
||
<span class="p">[</span><span class="n">mylink</span><span class="p">]:</span> <span class="n">http</span><span class="p">:</span><span class="o">//...</span>
|
||
<span class="p">[</span><span class="mi">1</span><span class="p">]:</span> <span class="n">My</span><span class="o">-</span><span class="n">Document</span><span class="o">.</span><span class="n">md</span><span class="c1">#this-is-a-long-ref</span>
|
||
|
||
</pre></div>
|
||
</div>
|
||
<p>This makes the main text a little shorter.</p>
|
||
</section>
|
||
<section id="tables">
|
||
<h3>Tables<a class="headerlink" href="#tables" title="Permalink to this headline">¶</a></h3>
|
||
<p>A table is done like this:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">|</span> <span class="n">heading1</span> <span class="o">|</span> <span class="n">heading2</span> <span class="o">|</span> <span class="n">heading3</span> <span class="o">|</span>
|
||
<span class="o">|</span> <span class="o">---</span> <span class="o">|</span> <span class="o">---</span> <span class="o">|</span> <span class="o">---</span> <span class="o">|</span>
|
||
<span class="o">|</span> <span class="n">value1</span> <span class="o">|</span> <span class="n">value2</span> <span class="o">|</span> <span class="n">value3</span> <span class="o">|</span>
|
||
<span class="o">|</span> <span class="o">|</span> <span class="n">value</span> <span class="mi">4</span> <span class="o">|</span> <span class="o">|</span>
|
||
<span class="o">|</span> <span class="n">value</span> <span class="mi">5</span> <span class="o">|</span> <span class="n">value</span> <span class="mi">6</span> <span class="o">|</span> <span class="o">|</span>
|
||
</pre></div>
|
||
</div>
|
||
<table class="colwidths-auto docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>heading1</p></th>
|
||
<th class="head"><p>heading2</p></th>
|
||
<th class="head"><p>heading3</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>value1</p></td>
|
||
<td><p>value2</p></td>
|
||
<td><p>value3</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p></p></td>
|
||
<td><p>value 4</p></td>
|
||
<td><p></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p>value 5</p></td>
|
||
<td><p>value 6</p></td>
|
||
<td><p></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<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 <code class="docutils literal notranslate"><span class="pre">|</span></code> on every line.</p>
|
||
</section>
|
||
<section id="verbatim-text">
|
||
<h3>Verbatim text<a class="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
|
||
<code class="docutils literal notranslate"><span class="pre">verbatim</span> <span class="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>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">This</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">text</span>
|
||
|
||
<span class="n">This</span> <span class="ow">is</span> <span class="n">verbatim</span> <span class="n">text</span>
|
||
|
||
<span class="n">This</span> <span class="ow">is</span> <span class="n">normal</span> <span class="n">text</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Another way is to use triple-backticks:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```
|
||
Everything within these backticks will be verbatim.
|
||
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="code-blocks">
|
||
<h3>Code blocks<a class="headerlink" href="#code-blocks" title="Permalink to this headline">¶</a></h3>
|
||
<p>A special ‘verbatim’ 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:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```python
|
||
from evennia import Command
|
||
class CmdEcho(Command):
|
||
"""
|
||
Usage: echo <arg>
|
||
"""
|
||
key = "echo"
|
||
def func(self):
|
||
self.caller.msg(self.args.strip())
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">Command</span>
|
||
<span class="k">class</span> <span class="nc">CmdEcho</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
|
||
<span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> Usage: echo <arg></span>
|
||
<span class="sd"> """</span>
|
||
<span class="n">key</span> <span class="o">=</span> <span class="s2">"echo"</span>
|
||
<span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="o">.</span><span class="n">strip</span><span class="p">())</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>For examples of using the Python command-line, use <code class="docutils literal notranslate"><span class="pre">python</span></code> language and <code class="docutils literal notranslate"><span class="pre">>>></span></code> prompt.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```python
|
||
>>> print("Hello World")
|
||
Hello World
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="s2">"Hello World"</span><span class="p">)</span>
|
||
<span class="go">Hello World</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>When showing an in-game command, use the <code class="docutils literal notranslate"><span class="pre">shell</span></code> language type and <code class="docutils literal notranslate"><span class="pre">></span></code> as the prompt.
|
||
Indent returns from the game.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```shell
|
||
> look at flower
|
||
Red Flower(#34)
|
||
A flower with red petals.
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>><span class="w"> </span>look<span class="w"> </span>at<span class="w"> </span>flower
|
||
<span class="w"> </span>Red<span class="w"> </span>Flower<span class="o">(</span><span class="c1">#34)</span>
|
||
<span class="w"> </span>A<span class="w"> </span>flower<span class="w"> </span>with<span class="w"> </span>red<span class="w"> </span>petals.
|
||
</pre></div>
|
||
</div>
|
||
<p>For actual shell prompts you can either use <code class="docutils literal notranslate"><span class="pre">bash</span></code> language type or just indent the line.
|
||
Use <code class="docutils literal notranslate"><span class="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>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```bash
|
||
$ ls
|
||
evennia/ mygame/
|
||
```
|
||
evennia start --log
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>ls
|
||
evennia/<span class="w"> </span>mygame/
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>evennia start --log
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="myst-directives">
|
||
<h3>MyST directives<a class="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 <a class="reference external" href="https://myst-parser.readthedocs.io/en/latest/syntax/reference.html">MyST</a> syntax. This is
|
||
on the form</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{directive} any_options_here
|
||
|
||
content
|
||
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<section id="note">
|
||
<h4>Note<a class="headerlink" href="#note" title="Permalink to this headline">¶</a></h4>
|
||
<p>This kind of note may pop more than doing a <code class="docutils literal notranslate"><span class="pre">></span> <span class="pre">Note:</span> <span class="pre">...</span></code>.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{note}
|
||
|
||
This is some noteworthy content that stretches over more than one line to show how the content indents.
|
||
Also the important/warning notes indents like this.
|
||
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This is some noteworthy content that stretches over more than one line to show how the content indents.
|
||
Also the important/warning notes indents like this.</p>
|
||
</div>
|
||
</section>
|
||
<section id="important">
|
||
<h4>Important<a class="headerlink" href="#important" title="Permalink to this headline">¶</a></h4>
|
||
<p>This is for particularly important and visible notes.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{important}
|
||
This is important because it is!
|
||
```
|
||
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>This is important because it is!</p>
|
||
</div>
|
||
</section>
|
||
<section id="warning">
|
||
<h4>Warning<a class="headerlink" href="#warning" title="Permalink to this headline">¶</a></h4>
|
||
<p>A warning block is used to draw attention to particularly dangerous things, or features easy to
|
||
mess up.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{warning}
|
||
Be careful about this ...
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Be careful about this …</p>
|
||
</div>
|
||
</section>
|
||
<section id="version-changes-and-deprecations">
|
||
<h4>Version changes and deprecations<a class="headerlink" href="#version-changes-and-deprecations" title="Permalink to this headline">¶</a></h4>
|
||
<p>These will show up as one-line warnings that suggest an added, changed or deprecated
|
||
feature beginning with particular version.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{versionadded} 1.0
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 1.0.</span></p>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{versionchanged} 1.0
|
||
How the feature changed with this version.
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 1.0: </span>How the feature changed with this version.</p>
|
||
</div>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{deprecated} 1.0
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 1.0.</span></p>
|
||
</div>
|
||
</section>
|
||
<section id="sidebar">
|
||
<h4>Sidebar<a class="headerlink" href="#sidebar" title="Permalink to this headline">¶</a></h4>
|
||
<p>This will display an informative sidebar that floats to the side of regular content. This is useful
|
||
for example to remind the reader of some concept relevant to the text.</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{sidebar} Things to remember
|
||
|
||
- There can be bullet lists
|
||
- in here.
|
||
|
||
Separate sections with
|
||
|
||
an empty line.
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<aside class="sidebar">
|
||
<p class="sidebar-title">Things to remember</p>
|
||
<ul class="simple">
|
||
<li><p>There can be bullet lists</p></li>
|
||
<li><p>in here.</p></li>
|
||
</ul>
|
||
<p>Separate sections with</p>
|
||
<p>an empty line.</p>
|
||
</aside>
|
||
<p>Hint: If wanting to make sure to have the next header appear on a row of its own (rather than
|
||
squeezed to the left of the sidebar), one can embed a plain HTML string in the markdown like so:</p>
|
||
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p"><</span><span class="nt">div</span> <span class="na">style</span><span class="o">=</span><span class="s">"clear: right;"</span><span class="p">></</span><span class="nt">div</span><span class="p">></span>
|
||
</pre></div>
|
||
</div>
|
||
<div style="clear: right;"></div>
|
||
</section>
|
||
<section id="a-more-flexible-code-block">
|
||
<h4>A more flexible code block<a class="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 <code class="docutils literal notranslate"><span class="pre">{code-block}</span></code> directive that takes a set of additional <code class="docutils literal notranslate"><span class="pre">:options:</span></code>:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{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())
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<div class="literal-block-wrapper docutils container" id="a-full-code-block-example">
|
||
<div class="code-block-caption"><span class="caption-text">An example code block</span><a class="headerlink" href="#a-full-code-block-example" title="Permalink to this code">¶</a></div>
|
||
<div class="highlight-python notranslate"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
|
||
<span class="normal">2</span>
|
||
<span class="normal">3</span>
|
||
<span class="normal">4</span>
|
||
<span class="normal">5</span>
|
||
<span class="normal">6</span>
|
||
<span class="normal">7</span>
|
||
<span class="normal">8</span></pre></div></td><td class="code"><div><pre><span></span><span class="hll"><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">Command</span>
|
||
</span><span class="hll"><span class="k">class</span> <span class="nc">CmdEcho</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
|
||
</span><span class="w"> </span><span class="sd">"""</span>
|
||
<span class="sd"> Usage: echo <arg></span>
|
||
<span class="sd"> """</span>
|
||
<span class="n">key</span> <span class="o">=</span> <span class="s2">"echo"</span>
|
||
<span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="hll"> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">msg</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">args</span><span class="o">.</span><span class="n">strip</span><span class="p">())</span>
|
||
</span></pre></div></td></tr></table></div>
|
||
</div>
|
||
</div>
|
||
<p>Here, <code class="docutils literal notranslate"><span class="pre">:linenos:</span></code> turns on line-numbers and <code class="docutils literal notranslate"><span class="pre">:emphasize-lines:</span></code> allows for emphasizing certain lines
|
||
in a different color. The <code class="docutils literal notranslate"><span class="pre">:caption:</span></code> shows an instructive text and <code class="docutils literal notranslate"><span class="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>
|
||
<section id="eval-rst-directive">
|
||
<h4>eval-rst directive<a class="headerlink" href="#eval-rst-directive" title="Permalink to this headline">¶</a></h4>
|
||
<p>As a last resort, we can also fall back to writing <a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html">ReST</a> directives directly:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>```{eval-rst}
|
||
|
||
This will be evaluated as ReST.
|
||
All content must be indented.
|
||
|
||
```
|
||
</pre></div>
|
||
</div>
|
||
<p>Within a ReST block, one must use Restructured Text syntax, which is not the
|
||
same as Markdown.</p>
|
||
<ul>
|
||
<li><p>Single backticks around text makes it <em>italic</em>.</p></li>
|
||
<li><p>Double backticks around text makes it <code class="docutils literal notranslate"><span class="pre">verbatim</span></code>.</p></li>
|
||
<li><p>A link is written within back-ticks, with an underscore at the end:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>`python <www.python.org>`_
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p><a class="reference external" href="https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html">Here is a ReST formatting cheat sheet</a>.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="writing-code-docstrings-for-autodocs">
|
||
<h2>Writing Code docstrings for autodocs<a class="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 (<code class="docutils literal notranslate"><span class="pre">####</span> <span class="pre">SubSubSubHeader</span></code>).</p>
|
||
<p>After the module documentation it’s a good idea to end with four dashes <code class="docutils literal notranslate"><span class="pre">----</span></code>. This will create a visible line between the documentation and the class/function docs to follow. See for example <a class="reference internal" href="api/evennia.contrib.rpg.traits.html#evennia-contrib-rpg-traits"><span class="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>
|
||
<section id="building-the-docs-locally">
|
||
<h2>Building the docs locally<a class="headerlink" href="#building-the-docs-locally" title="Permalink to this headline">¶</a></h2>
|
||
<p>Evennia leverages <a class="reference external" href="https://www.sphinx-doc.org/en/master/">Sphinx</a> with the <a class="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 <a class="reference external" href="https://spec.commonmark.org/current/">CommonMark</a>, like on github) rather than Sphinx’ normal ReST syntax. The <code class="docutils literal notranslate"><span class="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 <a class="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-<a class="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 <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">make</span></code> (Linux/Unix/Mac or <a class="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 <code class="docutils literal notranslate"><span class="pre">evennia/docs/Makefile</span></code> to see which commands are run by the <code class="docutils literal notranslate"><span class="pre">make</span></code>-commands referred to in this document.</p>
|
||
<div class="admonition important">
|
||
<p class="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 <a class="reference external" href="https://github.com/joeyespo/grip">Grip</a>. Editors like <a class="reference external" href="https://github.com/retext-project/retext">ReText</a> or IDE’s like <a class="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>
|
||
</div>
|
||
<section id="building-only-the-main-documentation">
|
||
<h3>Building only the main documentation<a class="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><code class="docutils literal notranslate"><span class="pre">cd</span></code> to into the <code class="docutils literal notranslate"><span class="pre">evennia/docs</span></code> folder.</p></li>
|
||
<li><p>Install the documentation-build requirements:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">install</span>
|
||
<span class="ow">or</span>
|
||
<span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">.</span><span class="n">txt</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Next, build the html-based documentation (re-run this in the future to build your changes):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">quick</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Note any errors from files you have edited.</p></li>
|
||
<li><p>The html-based documentation will appear in the new folder <code class="docutils literal notranslate"><span class="pre">evennia/docs/build/html/</span></code>.</p></li>
|
||
<li><p>Use a web browser to open <code class="docutils literal notranslate"><span class="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>
|
||
</ul>
|
||
</section>
|
||
<section id="building-the-main-documentation-and-api-docs">
|
||
<h3>Building the main documentation and API docs<a class="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 <code class="docutils literal notranslate"><span class="pre">/docs</span></code>):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">e</span> <span class="n">evennia</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Make sure you are in the parent folder <em>containing</em> your <code class="docutils literal notranslate"><span class="pre">evennia/</span></code> repo (so <em>two</em> levels up from <code class="docutils literal notranslate"><span class="pre">evennia/docs/</span></code>).</p></li>
|
||
<li><p>Create a new game folder called exactly <code class="docutils literal notranslate"><span class="pre">gamedir</span></code> at the same level as your <code class="docutils literal notranslate"><span class="pre">evennia</span></code> repo with</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="o">--</span><span class="n">init</span> <span class="n">gamedir</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Then <code class="docutils literal notranslate"><span class="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>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">evennia</span> <span class="n">migrate</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>This is how the structure should look at this point:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="p">(</span><span class="n">top</span><span class="p">)</span>
|
||
<span class="o">|</span>
|
||
<span class="o">-----</span> <span class="n">evennia</span><span class="o">/</span> <span class="p">(</span><span class="n">the</span> <span class="n">top</span><span class="o">-</span><span class="n">level</span> <span class="n">folder</span><span class="p">,</span> <span class="n">containing</span> <span class="n">docs</span><span class="o">/</span><span class="p">)</span>
|
||
<span class="o">|</span>
|
||
<span class="o">-----</span> <span class="n">gamedir</span><span class="o">/</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<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 <code class="docutils literal notranslate"><span class="pre">evennia/docs/</span></code> and install the doc-building requirements (you only need to do this once):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">install</span>
|
||
<span class="ow">or</span>
|
||
<span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">.</span><span class="n">txt</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Finally, build the full documentation, including the auto-docs:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">local</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>The rendered files will appear in a new folder <code class="docutils literal notranslate"><span class="pre">evennia/docs/build/html/</span></code>. Note any errors from files you have edited.</p></li>
|
||
<li><p>Point your web browser to <code class="docutils literal notranslate"><span class="pre">file://<path-to-folder>/evennia/docs/build/html/index.html</span></code> to view the full docs.</p></li>
|
||
</ul>
|
||
<section id="building-with-another-gamedir">
|
||
<h4>Building with another gamedir<a class="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 <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">EVGAMEDIR</span></code> environment variable to the absolute path of your alternative game dir. For example:</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">EVGAMEDIR</span><span class="o">=/</span><span class="n">my</span><span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">mygamedir</span> <span class="n">make</span> <span class="n">local</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="building-multiversion-docs">
|
||
<h3>Building multiversion docs<a class="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 (<code class="docutils literal notranslate"><span class="pre">mv</span></code> stands for “multi-version”):</p>
|
||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">mv</span><span class="o">-</span><span class="n">local</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>This is as close to the ‘real’ version of the docs as you can get locally. The different versions will be found under <code class="docutils literal notranslate"><span class="pre">evennia/docs/build/versions/</span></code>. During deploy a symlink <code class="docutils literal notranslate"><span class="pre">latest</span></code> will point to the latest version of the docs.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="Licensing.html" title="Licensing Q&A"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="Contributing.html" title="How To Contribute And Get Help"
|
||
>previous</a> |</li>
|
||
<li class="nav-item nav-item-0"><a href="index.html">Evennia 3.x</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">Contributing to Evennia Docs</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
<div class="admonition important">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">You are reading an old version of the Evennia documentation. <a href="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
|
||
</div>
|
||
|
||
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2023, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |