<li><p>All modules, classes, functions and methods should have doc strings formatted
as outlined below.</p></li>
<li><p>All default commands should have a consistent docstring formatted as
outlined below.</p></li>
</ul>
</section>
<sectionid="code-docstrings">
<h2>Code Docstrings<aclass="headerlink"href="#code-docstrings"title="Permalink to this headline">¶</a></h2>
<p>All modules, classes, functions and methods should have docstrings
formatted with <aclass="reference external"href="https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html">Google style</a> -inspired indents, using
<aclass="reference external"href="https://help.github.com/articles/github-flavored-markdown/">Markdown</a> formatting where needed. Evennia’s <codeclass="docutils literal notranslate"><spanclass="pre">api2md</span></code>
parser will use this to create pretty API documentation.</p>
<sectionid="module-docstrings">
<h3>Module docstrings<aclass="headerlink"href="#module-docstrings"title="Permalink to this headline">¶</a></h3>
<p>Modules should all start with at least a few lines of docstring at
their top describing the contents and purpose of the module.</p>
<spanclass="sd">This module handles the creation of `Objects` that</span>
<spanclass="sd">are useful in the game ...</span>
<spanclass="sd">"""</span>
</pre></div>
</div>
<p>Sectioning (<codeclass="docutils literal notranslate"><spanclass="pre">#</span><spanclass="pre">title</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">##</span><spanclass="pre">subtile</span></code> etc) should not be used in
freeform docstrings - this will confuse the sectioning of the auto
documentation page and the auto-api will create this automatically.
Write just the section name bolded on its own line to mark a section.
Beyond sections markdown should be used as needed to format
the text.</p>
<p>Code examples should use <aclass="reference external"href="https://help.github.com/articles/github-flavored-markdown/#syntax-highlighting">multi-line syntax highlighting</a>
to mark multi-line code blocks, using the “python” identifier. Just
indenting code blocks (common in markdown) will not produce the
desired look.</p>
<p>When using any code tags (inline or blocks) it’s recommended that you
don’t let the code extend wider than about 70 characters or it will
need to be scrolled horizontally in the wiki (this does not affect any
other text, only code).</p>
</section>
<sectionid="class-docstrings">
<h3>Class docstrings<aclass="headerlink"href="#class-docstrings"title="Permalink to this headline">¶</a></h3>
<p>The root class docstring should describe the over-arching use of the
class. It should usually not describe the exact call sequence nor list
important methods, this tends to be hard to keep updated as the API
<p>Parts marked with “freeform” means that you can in principle put any
text there using any formatting except for sections markers (<codeclass="docutils literal notranslate"><spanclass="pre">#</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">##</span></code>
etc). You must also keep indentation to mark which block you are part
of. You should normally use the specified format rather than the
freeform counterpart (this will produce nicer output) but in some
cases the freeform may produce a more compact and readable result
(such as when describing an <codeclass="docutils literal notranslate"><spanclass="pre">*args</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> statement in general
terms). The first <codeclass="docutils literal notranslate"><spanclass="pre">self</span></code> argument of class methods should never be
<p>mean the same thing! Which one is used depends on the function or
method documented, but there are no hard rules; If there is a large
<codeclass="docutils literal notranslate"><spanclass="pre">**kwargs</span></code> block in the function, using the <codeclass="docutils literal notranslate"><spanclass="pre">Keyword</span><spanclass="pre">Args:</span></code> block may be a
good idea, for a small number of arguments though, just using <codeclass="docutils literal notranslate"><spanclass="pre">Args:</span></code>
and marking keywords as <codeclass="docutils literal notranslate"><spanclass="pre">optional</span></code> will shorten the docstring and make
it easier to read.</p>
</section>
</section>
<sectionid="default-command-docstrings">
<h2>Default Command Docstrings<aclass="headerlink"href="#default-command-docstrings"title="Permalink to this headline">¶</a></h2>
<p>These represent a special case since Commands in Evennia use their class
docstrings to represent the in-game help entry for that command.</p>
<p>All the commands in the <em>default command</em> sets should have their doc-strings
formatted on a similar form. For contribs, this is loosened, but if there is
no particular reason to use a different form, one should aim to use the same
<li><p>Angled brackets <codeclass="docutils literal notranslate"><spanclass="pre"><</span><spanclass="pre">></span></code> surround a <em>description</em> of what to write rather than the exact syntax.</p></li>
<li><p>Explicit choices are separated by <codeclass="docutils literal notranslate"><spanclass="pre">|</span></code>. To avoid this being parsed as a color code, use <codeclass="docutils literal notranslate"><spanclass="pre">||</span></code> (this
will come out as a single <codeclass="docutils literal notranslate"><spanclass="pre">|</span></code>) or put spaces around the character (“<codeclass="docutils literal notranslate"><spanclass="pre">|</span></code>”) if there’s plenty of room.</p></li>
<li><p>The <codeclass="docutils literal notranslate"><spanclass="pre">Switches</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">Examples</span></code> blocks are optional and based on the Command.</p></li>
</ul>
<p>Here is the <codeclass="docutils literal notranslate"><spanclass="pre">nick</span></code> command as an example:</p>
<spanclass="sd"> account - alias an account</span>
<spanclass="sd"> clearall - clear all your aliases</span>
<spanclass="sd"> list - show all defined aliases (also "nicks" works)</span>
<spanclass="sd"> Examples:</span>
<spanclass="sd"> nick hi = say Hello, I'm Sarah!</span>
<spanclass="sd"> nick/object tom = the tall man</span>
<spanclass="sd"> A 'nick' is a personal shortcut you create for your own use [...]</span>
<spanclass="sd">"""</span>
</pre></div>
</div>
<p>For commands that <em>require arguments</em>, the policy is for it to return a <codeclass="docutils literal notranslate"><spanclass="pre">Usage:</span></code>
string if the command is entered without any arguments. So for such commands,
the Command body should contain something to the effect of</p>
