<p>Sub-topics are accessed as <codeclass="docutils literal notranslate"><spanclass="pre">help</span><spanclass="pre"><topic>/<subtopic>/...</span></code>.</p>
<p>Creating a new help entry from in-game is done with</p>
<p>Use the <codeclass="docutils literal notranslate"><spanclass="pre">/edit</span></code> switch to open the EvEditor for more convenient in-game writing
(but note that devs can also create help entries outside the game using their
regular code editor, see below).</p>
</div>
<divclass="section"id="sources-of-help-entries">
<h2>Sources of help entries<aclass="headerlink"href="#sources-of-help-entries"title="Permalink to this headline">¶</a></h2>
<p>Evennia collects help entries from three sources:</p>
<ulclass="simple">
<li><p><em>Auto-generated command help</em> - this is literally the doc-strings of the <aclass="reference internal"href="Commands.html"><spanclass="doc">Command classes</span></a>.
The idea is that the command docs are easier to maintain and keep up-to-date if
the developer can change them at the same time as they do the code.</p></li>
<li><p><em>Database-stored help entries</em> - These are created in-game (using the default <codeclass="docutils literal notranslate"><spanclass="pre">sethelp</span></code> command
as exemplified in the previous section).</p></li>
<li><p><em>File-stored help entries</em> - These are created outside the game, as dicts in
normal Python modules. They allows developers to write and maintain their help files using
a proper text editor.</p></li>
</ul>
<divclass="section"id="the-help-entry">
<h3>The Help Entry<aclass="headerlink"href="#the-help-entry"title="Permalink to this headline">¶</a></h3>
<p>All help entries (no matter the source) have the following properties:</p>
<ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> - This is the main topic-name. For Commands, this is literally the command’s <codeclass="docutils literal notranslate"><spanclass="pre">key</span></code>.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">aliases</span></code> - Alternate names for the help entry. This can be useful if the main name is hard to remember.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">help_category</span></code> - The general grouping of the entry. This is optional. If not given it will use the
default category given by <codeclass="docutils literal notranslate"><spanclass="pre">settings.COMMAND_DEFAULT_HELP_CATEGORY</span></code> for Commands and <codeclass="docutils literal notranslate"><spanclass="pre">settings.DEFAULT_HELP_CATEGORY</span></code>
for file+db help entries.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">locks</span></code> - This defines who may read this entry. The locktype checked by the <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> command is <codeclass="docutils literal notranslate"><spanclass="pre">view</span></code>. In the
case of Commands, it’s more common that the <codeclass="docutils literal notranslate"><spanclass="pre">cmd</span></code> lock fails - in that case the command is not loaded
into the help parser at all.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">tags</span></code> - This is not used by default, but could be used to further organize help entries.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> - The actual help entry text. This will be dedented and stripped of
extra space at beginning and end.</p></li>
</ul>
<p>A <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> that scrolls off the screen will automatically be paginated by
the <aclass="reference internal"href="EvMore.html"><spanclass="doc">EvMore</span></a> pager (you can control this with
<codeclass="docutils literal notranslate"><spanclass="pre">settings.HELP_MORE_ENABLED=False</span></code>). If you use EvMore and want to control
exactly where the pager should break the page, mark the break with the control
character <codeclass="docutils literal notranslate"><spanclass="pre">\f</span></code>.</p>
<divclass="section"id="subtopics">
<h4>Subtopics<aclass="headerlink"href="#subtopics"title="Permalink to this headline">¶</a></h4>
<divclass="versionadded">
<p><spanclass="versionmodified added">New in version 1.0.</span></p>
</div>
<p>Rather than making a very long help entry, the <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> may also be broken up
into <em>subtopics</em>. A list of the next level of subtopics are shown below the
main help text and allows the user to read more about some particular detail
that wouldn’t fit in the main text.</p>
<p>Subtopics use a markup slightly similar to markdown headings. The top level
heading must be named <codeclass="docutils literal notranslate"><spanclass="pre">#</span><spanclass="pre">subtopics</span></code> (non case-sensitive) and the following
headers must be sub-headings to this (so <codeclass="docutils literal notranslate"><spanclass="pre">##</span><spanclass="pre">subtopic</span><spanclass="pre">name</span></code> etc). All headings
are non-case sensitive (the help command will format them). The topics can be
nested at most to a depth of 5 (which is probably too many levels already). The
parser uses fuzzy matching to find the subtopic, so one does not have to type
it all out exactly.</p>
<p>Below is an example of a <codeclass="docutils literal notranslate"><spanclass="pre">text</span></code> with sub topics.</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span>The theatre is the heart of the city, here you can find ...
(This is the main help text, what you get with `help theatre`)
# subtopics
## lore
The theatre holds many mysterious things...
(`help theatre/lore`)
### the grand opening
The grand opening is the name for a mysterious event where ghosts appeared ...
(`this is a subsub-topic to lore, accessible as `help theatre/lore/grand` or
any other partial match).
### the Phantom
Deep under the theatre, rumors has it a monster hides ...
(another subsubtopic, accessible as `help theatre/lore/phantom`)
## layout
The theatre is a two-story building situated at ...
(`help theatre/layout`)
## dramatis personae
There are many interesting people prowling the halls of the theatre ...
(`help theatre/dramatis` or `help theathre/drama` or `help theatre/personae` would work)
### Primadonna Ada
Everyone knows the primadonna! She is ...
(A subtopic under dramatis personae, accessible as `help theatre/drama/ada` etc)
<p>The text at the very top of the command class definition is the class’<codeclass="docutils literal notranslate"><spanclass="pre">__doc__</span></code>-string and will be
shown to users looking for help. Try to use a consistent format - all default commands are using the
structure shown above.</p>
<p>You should also supply the <codeclass="docutils literal notranslate"><spanclass="pre">help_category</span></code> class property if you can; this helps to group help
entries together for people to more easily find them. See the <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> command in-game to see the
default categories. If you don’t specify the category, <codeclass="docutils literal notranslate"><spanclass="pre">settings.COMMAND_DEFAULT_HELP_CATEGORY</span></code>
<p>If you don’t want your command to be picked up by the auto-help system at all (like if you want to
write its docs manually using the info in the next section or you use a <aclass="reference internal"href="Command-Sets.html"><spanclass="doc">cmdset</span></a> that
has its own help functionality) you can explicitly set <codeclass="docutils literal notranslate"><spanclass="pre">auto_help</span></code> class property to <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code> in your
command definition.</p>
<p>Alternatively, you can keep the advantages of <em>auto-help</em> in commands, but control the display of
command helps. You can do so by overriding the command’s <codeclass="docutils literal notranslate"><spanclass="pre">get_help(caller,</span><spanclass="pre">cmdset)</span></code> method. By default, this
<h3>Database-help entries<aclass="headerlink"href="#database-help-entries"title="Permalink to this headline">¶</a></h3>
<p>These are most commonly created in-game using the <codeclass="docutils literal notranslate"><spanclass="pre">sethelp</span></code> command. If you need to create one
manually, you can do so with <codeclass="docutils literal notranslate"><spanclass="pre">evennia.create_help_entry()</span></code>:</p>
<p>The entity being created is a <aclass="reference external"href="../api/evennia.help.models.HelpEntry.html">evennia.help.models.HelpEntry</a>
object. This is <em>not</em> a <aclass="reference internal"href="Typeclasses.html"><spanclass="doc">Typeclassed</span></a> entity and is not meant to
be modified to any great degree. It holds the properties listed earlier. The
text is stored in a field <codeclass="docutils literal notranslate"><spanclass="pre">entrytext</span></code>. It does not provide a <codeclass="docutils literal notranslate"><spanclass="pre">get_help</span></code> method
like commands, stores and returns the <codeclass="docutils literal notranslate"><spanclass="pre">entrytext</span></code> directly.</p>
<p>You can search for <codeclass="docutils literal notranslate"><spanclass="pre">HelpEntry</span></code> objects using <codeclass="docutils literal notranslate"><spanclass="pre">evennia.search_help</span></code> but note
that this will not return the two other types of help entries.</p>
<p>File-help entries are created by the game development team outside of the game. The
help entries are defined in normal Python modules (<codeclass="docutils literal notranslate"><spanclass="pre">.py</span></code> file ending) containing
a <codeclass="docutils literal notranslate"><spanclass="pre">dict</span></code> to represent each entry. They require a server <codeclass="docutils literal notranslate"><spanclass="pre">reload</span></code> before any changes
apply.</p>
<ulclass="simple">
<li><p>Evennia will look through all modules given by <codeclass="docutils literal notranslate"><spanclass="pre">settings.FILE_HELP_ENTRY_MODULES</span></code>. This
should be a list of python-paths for Evennia to import.</p></li>
<li><p>If this module contains a top-level variable <codeclass="docutils literal notranslate"><spanclass="pre">HELP_ENTRY_DICTS</span></code>, this will be imported
and must be a <codeclass="docutils literal notranslate"><spanclass="pre">list</span></code> of help-entry dicts.</p></li>
<li><p>If no <codeclass="docutils literal notranslate"><spanclass="pre">HELP_ENTRY_DICTS</span></code> list is found, <em>every</em> top-level variable in the
module that is a <codeclass="docutils literal notranslate"><spanclass="pre">dict</span></code> will be read as a help entry. The variable-names will
be ignored in this case.</p></li>
</ul>
<p>If you add multiple modules to be read, same-keyed help entries added later in the list
will override coming before.</p>
<p>Each entry dict must define keys to match that needed by all help entries.
<spanclass="s2">"key"</span><spanclass="p">:</span><spanclass="s2">"The Gods"</span><spanclass="p">,</span><spanclass="c1"># case-insensitive, can be searched by 'gods' too</span>
<h2>Customizing the look of the help system<aclass="headerlink"href="#customizing-the-look-of-the-help-system"title="Permalink to this headline">¶</a></h2>
<p>This is done almost exclusively by overriding the <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> command
<p>Since the available commands may vary from moment to moment, <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> is
responsible for collating the three sources of help-entries (commands/db/file)
together and search through them on the fly. It also does all the formatting of
the output.</p>
<p>To make it easier to tweak the look, the parts of the code that changes the
visual presentation has been broken out into separate methods <codeclass="docutils literal notranslate"><spanclass="pre">format_help_entry</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">format_help_index</span></code> - override these in your version of <codeclass="docutils literal notranslate"><spanclass="pre">help</span></code> to change the display
as you please. See the api link above for details.</p>
</div>
<divclass="section"id="technical-notes">
<h2>Technical notes<aclass="headerlink"href="#technical-notes"title="Permalink to this headline">¶</a></h2>
<p>Since it needs to search so different types of data, the help system has to
collect all possibilities in memory before searching through the entire set. It
uses the <aclass="reference external"href="https://github.com/yeraydiazdiaz/lunr.py">Lunr</a> search engine to
search through the main bulk of help entries. Lunr is a mature engine used for
web-pages and produces much more sensible results than previous solutions.</p>
<p>Once the main entry has been found, subtopics are then searched with
simple <codeclass="docutils literal notranslate"><spanclass="pre">==</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">startswith</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">in</span></code> matching (there are so relatively few of them
at that point).</p>
<divclass="versionchanged">
<p><spanclass="versionmodified changed">Changed in version 1.0: </span>Replaced the bag-of-words algorithm with lunr.</p>
