mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
Updated HTML docs
This commit is contained in:
Griatch
parent
485838ffe2
commit
effa0f90f0
128 changed files with 8699 additions and 4764 deletions
|
|
@ -39,34 +39,154 @@
|
|||
|
||||
<div class="section" id="help-system">
|
||||
<h1>Help System<a class="headerlink" href="#help-system" title="Permalink to this headline">¶</a></h1>
|
||||
<p>An important part of Evennia is the online help system. This allows the players and staff alike to
|
||||
learn how to use the game’s commands as well as other information pertinent to the game. The help
|
||||
system has many different aspects, from the normal editing of help entries from inside the game, to
|
||||
auto-generated help entries during code development using the <em>auto-help system</em>.</p>
|
||||
<div class="section" id="viewing-the-help-database">
|
||||
<h2>Viewing the help database<a class="headerlink" href="#viewing-the-help-database" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The main command is <code class="docutils literal notranslate"><span class="pre">help</span></code>:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">help</span> <span class="p">[</span><span class="n">searchstring</span><span class="p">]</span>
|
||||
<p>Evennia has an extensive help system covering both command-help and regular
|
||||
free-form help documentation. It supports subtopics and if failing to find a
|
||||
match it will provide suggestsions, first from alternative topics and then by
|
||||
finding mentions of the search term in help entries.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">------------------------------------------------------------------------------</span>
|
||||
<span class="n">Help</span> <span class="k">for</span> <span class="n">The</span> <span class="n">theatre</span> <span class="p">(</span><span class="n">aliases</span><span class="p">:</span> <span class="n">the</span> <span class="n">hub</span><span class="p">,</span> <span class="n">curtains</span><span class="p">)</span>
|
||||
|
||||
<span class="n">The</span> <span class="n">theatre</span> <span class="ow">is</span> <span class="n">at</span> <span class="n">the</span> <span class="n">centre</span> <span class="n">of</span> <span class="n">the</span> <span class="n">city</span><span class="p">,</span> <span class="n">both</span> <span class="n">literally</span> <span class="ow">and</span> <span class="n">figuratively</span> <span class="o">...</span>
|
||||
<span class="p">(</span><span class="n">A</span> <span class="n">lot</span> <span class="n">more</span> <span class="n">text</span> <span class="n">about</span> <span class="n">it</span> <span class="n">follows</span> <span class="o">...</span><span class="p">)</span>
|
||||
|
||||
<span class="n">Subtopics</span><span class="p">:</span>
|
||||
<span class="n">theatre</span><span class="o">/</span><span class="n">lore</span>
|
||||
<span class="n">theatre</span><span class="o">/</span><span class="n">layout</span>
|
||||
<span class="n">theatre</span><span class="o">/</span><span class="n">dramatis</span> <span class="n">personae</span>
|
||||
<span class="o">------------------------------------------------------------------------------</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This will show a list of help entries, ordered after categories. You will find two sections,
|
||||
<em>Command help entries</em> and <em>Other help entries</em> (initially you will only have the first one). You
|
||||
can use help to get more info about an entry; you can also give partial matches to get suggestions.
|
||||
If you give category names you will only be shown the topics in that category.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">------------------------------------------------------------------------------</span>
|
||||
<span class="n">No</span> <span class="n">help</span> <span class="n">found</span>
|
||||
|
||||
<span class="n">There</span> <span class="ow">is</span> <span class="n">no</span> <span class="n">help</span> <span class="n">topic</span> <span class="n">matching</span> <span class="s1">'evennia'</span><span class="o">.</span>
|
||||
<span class="o">...</span> <span class="n">But</span> <span class="n">matches</span> <span class="n">where</span> <span class="n">found</span> <span class="n">within</span> <span class="n">the</span> <span class="n">help</span> <span class="n">texts</span> <span class="n">of</span> <span class="n">the</span> <span class="n">suggestions</span> <span class="n">below</span><span class="o">.</span>
|
||||
|
||||
<span class="n">Suggestions</span><span class="p">:</span>
|
||||
<span class="n">grapevine2chan</span><span class="p">,</span> <span class="n">about</span><span class="p">,</span> <span class="n">irc2chan</span>
|
||||
<span class="o">-----------------------------------------------------------------------------</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="using-the-help-system-from-in-game">
|
||||
<h2>Using the help system from in-game<a class="headerlink" href="#using-the-help-system-from-in-game" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The help system is accessed in-game by use of the <code class="docutils literal notranslate"><span class="pre">help</span></code> command:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">help</span> <span class="o"><</span><span class="n">topic</span><span class="o">></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Sub-topics are accessed as <code class="docutils literal notranslate"><span class="pre">help</span> <span class="pre"><topic>/<subtopic>/...</span></code>.</p>
|
||||
<p>Creating a new help entry from in-game is done with</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sethelp</span> <span class="o"><</span><span class="n">topic</span><span class="o">></span><span class="p">[;</span><span class="n">aliases</span><span class="p">]</span> <span class="p">[,</span><span class="n">category</span><span class="p">]</span> <span class="p">[,</span><span class="n">lockstring</span><span class="p">]</span> <span class="o">=</span> <span class="o"><</span><span class="n">text</span><span class="o">></span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>For example</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sethelp</span> <span class="n">The</span> <span class="n">Gods</span><span class="p">;</span><span class="n">pantheon</span><span class="p">,</span> <span class="n">Lore</span> <span class="o">=</span> <span class="n">In</span> <span class="n">the</span> <span class="n">beginning</span> <span class="nb">all</span> <span class="n">was</span> <span class="n">dark</span> <span class="o">...</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Use the <code class="docutils literal notranslate"><span class="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>
|
||||
<div class="section" id="sources-of-help-entries">
|
||||
<h2>Sources of help entries<a class="headerlink" href="#sources-of-help-entries" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Evennia collects help entries from three sources:</p>
|
||||
<ul class="simple">
|
||||
<li><p><em>Auto-generated command help</em> - this is literally the doc-strings of the <a class="reference internal" href="Commands.html"><span class="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 <code class="docutils literal notranslate"><span class="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>
|
||||
<div class="section" id="the-help-entry">
|
||||
<h3>The Help Entry<a class="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>
|
||||
<ul class="simple">
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">key</span></code> - This is the main topic-name. For Commands, this is literally the command’s <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="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><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">settings.COMMAND_DEFAULT_HELP_CATEGORY</span></code> for Commands and <code class="docutils literal notranslate"><span class="pre">settings.DEFAULT_HELP_CATEGORY</span></code>
|
||||
for file+db help entries.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">locks</span></code> - This defines who may read this entry. The locktype checked by the <code class="docutils literal notranslate"><span class="pre">help</span></code> command is <code class="docutils literal notranslate"><span class="pre">view</span></code>. In the
|
||||
case of Commands, it’s more common that the <code class="docutils literal notranslate"><span class="pre">cmd</span></code> lock fails - in that case the command is not loaded
|
||||
into the help parser at all.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">tags</span></code> - This is not used by default, but could be used to further organize help entries.</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">text</span></code> that scrolls off the screen will automatically be paginated by
|
||||
the <a class="reference internal" href="EvMore.html"><span class="doc">EvMore</span></a> pager (you can control this with
|
||||
<code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">\f</span></code>.</p>
|
||||
<div class="section" id="subtopics">
|
||||
<h4>Subtopics<a class="headerlink" href="#subtopics" title="Permalink to this headline">¶</a></h4>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in version 1.0.</span></p>
|
||||
</div>
|
||||
<p>Rather than making a very long help entry, the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">subtopics</span></code> (non case-sensitive) and the following
|
||||
headers must be sub-headings to this (so <code class="docutils literal notranslate"><span class="pre">##</span> <span class="pre">subtopic</span> <span class="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 <code class="docutils literal notranslate"><span class="pre">text</span></code> with sub topics.</p>
|
||||
<div class="highlight-default notranslate"><div class="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)
|
||||
|
||||
### The gatekeeper
|
||||
|
||||
He always keeps an eye on the door and ...
|
||||
(`help theatre/drama/gate`)
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="command-auto-help-system">
|
||||
<h2>Command Auto-help system<a class="headerlink" href="#command-auto-help-system" title="Permalink to this headline">¶</a></h2>
|
||||
<p>A common item that requires help entries are in-game commands. Keeping these entries up-to-date with
|
||||
the actual source code functionality can be a chore. Evennia’s commands are therefore auto-
|
||||
documenting straight from the sources through its <em>auto-help system</em>. Only commands that you and
|
||||
your character can actually currently use are picked up by the auto-help system. That means an admin
|
||||
will see a considerably larger amount of help topics than a normal player when using the default
|
||||
<code class="docutils literal notranslate"><span class="pre">help</span></code> command.</p>
|
||||
<p>The auto-help system uses the <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> strings of your command classes and formats this to a nice-
|
||||
looking help entry. This makes for a very easy way to keep the help updated - just document your
|
||||
commands well and updating the help file is just a <code class="docutils literal notranslate"><span class="pre">@reload</span></code> away. There is no need to manually
|
||||
create and maintain help database entries for commands; as long as you keep the docstrings updated
|
||||
your help will be dynamically updated for you as well.</p>
|
||||
<h3>Command Auto-help system<a class="headerlink" href="#command-auto-help-system" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The auto-help system uses the <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> strings of your command classes and
|
||||
formats this to a nice- looking help entry. This makes for a very easy way to
|
||||
keep the help updated - just document your commands well and updating the help
|
||||
file is just a <code class="docutils literal notranslate"><span class="pre">reload</span></code> away.</p>
|
||||
<p>Example (from a module with command definitions):</p>
|
||||
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
|
||||
2
|
||||
|
|
@ -114,59 +234,157 @@ shown to users looking for help. Try to use a consistent format - all default co
|
|||
structure shown above.</p>
|
||||
<p>You should also supply the <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">help</span></code> command in-game to see the
|
||||
default categories. If you don’t specify the category, “General” is assumed.</p>
|
||||
default categories. If you don’t specify the category, <code class="docutils literal notranslate"><span class="pre">settings.COMMAND_DEFAULT_HELP_CATEGORY</span></code>
|
||||
(default is “General”) is used.</p>
|
||||
<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 <a class="reference internal" href="Command-Sets.html"><span class="doc">cmdset</span></a> that
|
||||
has its own help functionality) you can explicitly set <code class="docutils literal notranslate"><span class="pre">auto_help</span></code> class property to <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">get_help()</span></code> method. By default, this
|
||||
command helps. You can do so by overriding the command’s <code class="docutils literal notranslate"><span class="pre">get_help(caller,</span> <span class="pre">cmdset)</span></code> method. By default, this
|
||||
method will return the class docstring. You could modify it to add custom behavior: the text
|
||||
returned by this method will be displayed to the character asking for help in this command.</p>
|
||||
</div>
|
||||
<div class="section" id="database-help-entries">
|
||||
<h2>Database help entries<a class="headerlink" href="#database-help-entries" title="Permalink to this headline">¶</a></h2>
|
||||
<p>These are all help entries not involving commands (this is handled automatically by the <a class="reference external" href="Components/Help-System.html#command-auto-help-system">Command
|
||||
Auto-help system</a>). Non-automatic help entries describe how
|
||||
your particular game is played - its rules, world descriptions and so on.</p>
|
||||
<p>A help entry consists of four parts:</p>
|
||||
<ul class="simple">
|
||||
<li><p>The <em>topic</em>. This is the name of the help entry. This is what players search for when they are
|
||||
looking for help. The topic can contain spaces and also partial matches will be found.</p></li>
|
||||
<li><p>The <em>help category</em>. Examples are <em>Administration</em>, <em>Building</em>, <em>Comms</em> or <em>General</em>. This is an
|
||||
overall grouping of similar help topics, used by the engine to give a better overview.</p></li>
|
||||
<li><p>The <em>text</em> - the help text itself, of any length.</p></li>
|
||||
<li><p>locks - a <a class="reference internal" href="Locks.html"><span class="doc">lock definition</span></a>. This can be used to limit access to this help entry, maybe
|
||||
because it’s staff-only or otherwise meant to be restricted. Help commands check for <code class="docutils literal notranslate"><span class="pre">access_type</span></code>s
|
||||
<code class="docutils literal notranslate"><span class="pre">view</span></code> and <code class="docutils literal notranslate"><span class="pre">edit</span></code>. An example of a lock string would be <code class="docutils literal notranslate"><span class="pre">view:perm(Builders)</span></code>.</p></li>
|
||||
</ul>
|
||||
<p>You can create new help entries in code by using <code class="docutils literal notranslate"><span class="pre">evennia.create_help_entry()</span></code>.</p>
|
||||
<h3>Database-help entries<a class="headerlink" href="#database-help-entries" title="Permalink to this headline">¶</a></h3>
|
||||
<p>These are most commonly created in-game using the <code class="docutils literal notranslate"><span class="pre">sethelp</span></code> command. If you need to create one
|
||||
manually, you can do so with <code class="docutils literal notranslate"><span class="pre">evennia.create_help_entry()</span></code>:</p>
|
||||
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1
|
||||
2
|
||||
3
|
||||
4</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">create_help_entry</span>
|
||||
4
|
||||
5</pre></div></td><td class="code"><div class="highlight"><pre><span></span>
|
||||
<span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">create_help_entry</span>
|
||||
<span class="n">entry</span> <span class="o">=</span> <span class="n">create_help_entry</span><span class="p">(</span><span class="s2">"emote"</span><span class="p">,</span>
|
||||
<span class="s2">"Emoting is important because ..."</span><span class="p">,</span>
|
||||
<span class="n">category</span><span class="o">=</span><span class="s2">"Roleplaying"</span><span class="p">,</span> <span class="n">locks</span><span class="o">=</span><span class="s2">"view:all()"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</td></tr></table></div>
|
||||
<p>From inside the game those with the right permissions can use the <code class="docutils literal notranslate"><span class="pre">@sethelp</span></code> command to add and
|
||||
modify help entries.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">></span> <span class="nd">@sethelp</span><span class="o">/</span><span class="n">add</span> <span class="n">emote</span> <span class="o">=</span> <span class="n">The</span> <span class="n">emote</span> <span class="n">command</span> <span class="ow">is</span> <span class="o">...</span>
|
||||
</pre></div>
|
||||
<p>The entity being created is a <a class="reference external" href="../api/evennia.help.models.HelpEntry.html">evennia.help.models.HelpEntry</a>
|
||||
object. This is <em>not</em> a <a class="reference internal" href="Typeclasses.html"><span class="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 <code class="docutils literal notranslate"><span class="pre">entrytext</span></code>. It does not provide a <code class="docutils literal notranslate"><span class="pre">get_help</span></code> method
|
||||
like commands, stores and returns the <code class="docutils literal notranslate"><span class="pre">entrytext</span></code> directly.</p>
|
||||
<p>You can search for <code class="docutils literal notranslate"><span class="pre">HelpEntry</span></code> objects using <code class="docutils literal notranslate"><span class="pre">evennia.search_help</span></code> but note
|
||||
that this will not return the two other types of help entries.</p>
|
||||
</div>
|
||||
<p>Using <code class="docutils literal notranslate"><span class="pre">@sethelp</span></code> you can add, delete and append text to existing entries. By default new entries
|
||||
will go in the <em>General</em> help category. You can change this using a different form of the <code class="docutils literal notranslate"><span class="pre">@sethelp</span></code>
|
||||
command:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">></span> <span class="nd">@sethelp</span><span class="o">/</span><span class="n">add</span> <span class="n">emote</span><span class="p">,</span> <span class="n">Roleplaying</span> <span class="o">=</span> <span class="n">Emoting</span> <span class="ow">is</span> <span class="n">important</span> <span class="n">because</span> <span class="o">...</span>
|
||||
</pre></div>
|
||||
<div class="section" id="file-help-entries">
|
||||
<h3>File-help entries<a class="headerlink" href="#file-help-entries" title="Permalink to this headline">¶</a></h3>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in version 1.0.</span></p>
|
||||
</div>
|
||||
<p>If the category <em>Roleplaying</em> did not already exist, it is created and will appear in the help
|
||||
index.</p>
|
||||
<p>You can, finally, define a lock for the help entry by following the category with a <a class="reference internal" href="Locks.html"><span class="doc">lock
|
||||
definition</span></a>:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">></span> <span class="nd">@sethelp</span><span class="o">/</span><span class="n">add</span> <span class="n">emote</span><span class="p">,</span> <span class="n">Roleplaying</span><span class="p">,</span> <span class="n">view</span><span class="p">:</span><span class="nb">all</span><span class="p">()</span> <span class="o">=</span> <span class="n">Emoting</span> <span class="ow">is</span> <span class="o">...</span>
|
||||
<p>File-help entries are created by the game development team outside of the game. The
|
||||
help entries are defined in normal Python modules (<code class="docutils literal notranslate"><span class="pre">.py</span></code> file ending) containing
|
||||
a <code class="docutils literal notranslate"><span class="pre">dict</span></code> to represent each entry. They require a server <code class="docutils literal notranslate"><span class="pre">reload</span></code> before any changes
|
||||
apply.</p>
|
||||
<ul class="simple">
|
||||
<li><p>Evennia will look through all modules given by <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">HELP_ENTRY_DICTS</span></code>, this will be imported
|
||||
and must be a <code class="docutils literal notranslate"><span class="pre">list</span></code> of help-entry dicts.</p></li>
|
||||
<li><p>If no <code class="docutils literal notranslate"><span class="pre">HELP_ENTRY_DICTS</span></code> list is found, <em>every</em> top-level variable in the
|
||||
module that is a <code class="docutils literal notranslate"><span class="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.
|
||||
Here’s an example of a help module:</p>
|
||||
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7
|
||||
8
|
||||
9
|
||||
10
|
||||
11
|
||||
12
|
||||
13
|
||||
14
|
||||
15
|
||||
16
|
||||
17
|
||||
18
|
||||
19
|
||||
20
|
||||
21
|
||||
22
|
||||
23
|
||||
24
|
||||
25
|
||||
26
|
||||
27
|
||||
28
|
||||
29
|
||||
30
|
||||
31
|
||||
32</pre></div></td><td class="code"><div class="highlight"><pre><span></span>
|
||||
<span class="c1"># in a module pointed to by settings.FILE_HELP_ENTRY_MODULES</span>
|
||||
|
||||
<span class="n">HELP_ENTRY_DICTS</span> <span class="o">=</span> <span class="p">[</span>
|
||||
<span class="p">{</span>
|
||||
<span class="s2">"key"</span><span class="p">:</span> <span class="s2">"The Gods"</span><span class="p">,</span> <span class="c1"># case-insensitive, can be searched by 'gods' too</span>
|
||||
<span class="s2">"aliases"</span><span class="p">:</span> <span class="p">[</span><span class="s1">'pantheon'</span><span class="p">,</span> <span class="s1">'religion'</span><span class="p">]</span>
|
||||
<span class="s2">"category"</span><span class="p">:</span> <span class="s2">"Lore"</span><span class="p">,</span>
|
||||
<span class="s2">"text"</span><span class="p">:</span> <span class="s1">'''</span>
|
||||
<span class="s1"> The gods formed the world ...</span>
|
||||
|
||||
<span class="s1"> # Subtopics</span>
|
||||
|
||||
<span class="s1"> ## Pantheon</span>
|
||||
|
||||
<span class="s1"> The pantheon consists of 40 gods that ...</span>
|
||||
|
||||
<span class="s1"> ### God of love</span>
|
||||
|
||||
<span class="s1"> The most prominent god is ...</span>
|
||||
|
||||
<span class="s1"> ### God of war</span>
|
||||
|
||||
<span class="s1"> Also known as 'the angry god', this god is known to ...</span>
|
||||
|
||||
<span class="s1"> '''</span>
|
||||
<span class="p">},</span>
|
||||
<span class="p">{</span>
|
||||
<span class="s2">"key"</span><span class="p">:</span> <span class="s2">"The mortals"</span><span class="p">,</span>
|
||||
|
||||
<span class="p">}</span>
|
||||
<span class="p">]</span>
|
||||
</pre></div>
|
||||
</td></tr></table></div>
|
||||
<p>The help entry text will be dedented and will retain paragraphs. You should try
|
||||
to keep your strings a reasonable width (it will look better). Just reload the
|
||||
server and the file-based help entries will be available to view.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="customizing-the-look-of-the-help-system">
|
||||
<h2>Customizing the look of the help system<a class="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 <code class="docutils literal notranslate"><span class="pre">help</span></code> command
|
||||
<a class="reference external" href="../api/evennia.commands.default.help.html#CmdHelp">evennia.commands.default.help.CmdHelp</a>.</p>
|
||||
<p>Since the available commands may vary from moment to moment, <code class="docutils literal notranslate"><span class="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 <code class="docutils literal notranslate"><span class="pre">format_help_entry</span></code> and
|
||||
<code class="docutils literal notranslate"><span class="pre">format_help_index</span></code> - override these in your version of <code class="docutils literal notranslate"><span class="pre">help</span></code> to change the display
|
||||
as you please. See the api link above for details.</p>
|
||||
</div>
|
||||
<div class="section" id="technical-notes">
|
||||
<h2>Technical notes<a class="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 <a class="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 <code class="docutils literal notranslate"><span class="pre">==</span></code>, <code class="docutils literal notranslate"><span class="pre">startswith</span></code> and <code class="docutils literal notranslate"><span class="pre">in</span></code> matching (there are so relatively few of them
|
||||
at that point).</p>
|
||||
<div class="versionchanged">
|
||||
<p><span class="versionmodified changed">Changed in version 1.0: </span>Replaced the bag-of-words algorithm with lunr.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -194,9 +412,19 @@ definition</span></a>:</p>
|
|||
<p><h3><a href="../index.html">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">Help System</a><ul>
|
||||
<li><a class="reference internal" href="#viewing-the-help-database">Viewing the help database</a></li>
|
||||
<li><a class="reference internal" href="#using-the-help-system-from-in-game">Using the help system from in-game</a></li>
|
||||
<li><a class="reference internal" href="#sources-of-help-entries">Sources of help entries</a><ul>
|
||||
<li><a class="reference internal" href="#the-help-entry">The Help Entry</a><ul>
|
||||
<li><a class="reference internal" href="#subtopics">Subtopics</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#command-auto-help-system">Command Auto-help system</a></li>
|
||||
<li><a class="reference internal" href="#database-help-entries">Database help entries</a></li>
|
||||
<li><a class="reference internal" href="#database-help-entries">Database-help entries</a></li>
|
||||
<li><a class="reference internal" href="#file-help-entries">File-help entries</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#customizing-the-look-of-the-help-system">Customizing the look of the help system</a></li>
|
||||
<li><a class="reference internal" href="#technical-notes">Technical notes</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue