Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-18 22:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated HTML docs

Browse source
This commit is contained in:
Griatch 2021-10-26 21:41:11 +02:00
parent 66d0ad0bc9
commit 7900aad365
2073 changed files with 32986 additions and 41197 deletions
Download patch file Download diff file Expand all files Collapse all files

123
docs/1.0-dev/Components/Help-System.html
View file

@ -14,6 +14,8 @@
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"processClass": "tex2jax_process|mathjax_process|math|output_area"}})</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" />
@ -38,13 +40,13 @@
<div class="bodywrapper">
<div class="body" role="main">
<section id="help-system">
<section class="tex2jax_ignore mathjax_ignore" id="help-system">
<h1>Help System<a class="headerlink" href="#help-system" title="Permalink to this headline"></a></h1>
<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">&gt;</span> <span class="n">help</span> <span class="n">theatre</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; help theatre
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">------------------------------------------------------------------------------</span>
@ -60,7 +62,7 @@ finding mentions of the search term in help entries.</p>
<span class="o">------------------------------------------------------------------------------</span>
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">&gt;</span> <span class="n">help</span> <span class="n">evennia</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&gt; help evennia
</pre></div>
</div>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">------------------------------------------------------------------------------</span>
@ -77,16 +79,16 @@ finding mentions of the search term in help entries.</p>
<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">&lt;</span><span class="n">topic</span><span class="o">&gt;</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>help &lt;topic&gt;
</pre></div>
</div>
<p>Sub-topics are accessed as <code class="docutils literal notranslate"><span class="pre">help</span> <span class="pre">&lt;topic&gt;/&lt;subtopic&gt;/...</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">&lt;</span><span class="n">topic</span><span class="o">&gt;</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">&lt;</span><span class="n">text</span><span class="o">&gt;</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sethelp &lt;topic&gt;[;aliases] [,category] [,lockstring] = &lt;text&gt;
</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>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>sethelp The Gods;pantheon, Lore = In the beginning all was dark ...
</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
@ -102,7 +104,7 @@ regular code editor, see below).</p>
<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
the <a class="reference internal" href="Commands.html"><span class="doc std std-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
@ -131,7 +133,7 @@ help entries.</p></li>
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
the <a class="reference internal" href="EvMore.html"><span class="doc std std-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>
@ -192,6 +194,7 @@ Everyone knows the primadonna! She is ...
He always keeps an eye on the door and ...
(`help theatre/drama/gate`)
</pre></div>
</div>
</section>
@ -203,27 +206,7 @@ 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><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>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span>
<span class="normal">21</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="k">class</span> <span class="nc">CmdMyCmd</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="k">class</span> <span class="nc">CmdMyCmd</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> mycmd - my very own command</span>
@ -245,12 +228,12 @@ file is just a <code class="docutils literal notranslate"><span class="pre">relo
<span class="c1"># [...]</span>
</pre></div>
</td></tr></table></div>
</div>
<p>The text at the very top of the command class definition is the class’
<code class="docutils literal notranslate"><span class="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 can limit access to the help entry by the <code class="docutils literal notranslate"><span class="pre">view</span></code> and/or <code class="docutils literal notranslate"><span class="pre">read</span></code> locks on the
Command. See <a class="reference external" href="#Locking-help-entries">the section below</a> for details.</p>
Command. See <a class="reference internal" href="#locking-help-entries"><span class="std std-doc">the section below</span></a> for details.</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
@ -258,7 +241,7 @@ category, <code class="docutils literal notranslate"><span class="pre">settings.
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
or you use a <a class="reference internal" href="Command-Sets.html"><span class="doc std std-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
@ -272,19 +255,15 @@ command.</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><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></pre></div></td><td class="code"><div class="highlight"><pre><span></span>
<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">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">&quot;emote&quot;</span><span class="p">,</span>
<span class="s2">&quot;Emoting is important because ...&quot;</span><span class="p">,</span>
<span class="n">category</span><span class="o">=</span><span class="s2">&quot;Roleplaying&quot;</span><span class="p">,</span> <span class="n">locks</span><span class="o">=</span><span class="s2">&quot;view:all()&quot;</span><span class="p">)</span>
</pre></div>
</td></tr></table></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
</div>
<p>The entity being created is a <a class="reference internal" href="../api/evennia.help.models.html#evennia.help.models.HelpEntry" title="evennia.help.models.HelpEntry"><span class="xref myst py py-class">evennia.help.models.HelpEntry</span></a>
object. This is <em>not</em> a <a class="reference internal" href="Typeclasses.html"><span class="doc std std-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>
@ -314,39 +293,7 @@ be ignored in this case.</p></li>
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><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>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span>
<span class="normal">21</span>
<span class="normal">22</span>
<span class="normal">23</span>
<span class="normal">24</span>
<span class="normal">25</span>
<span class="normal">26</span>
<span class="normal">27</span>
<span class="normal">28</span>
<span class="normal">29</span>
<span class="normal">30</span>
<span class="normal">31</span>
<span class="normal">32</span>
<span class="normal">33</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span>
<div class="highlight-python notranslate"><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>
@ -379,8 +326,9 @@ Here’s an example of a help module:</p>
<span class="p">}</span>
<span class="p">]</span>
</pre></div>
</td></tr></table></div>
</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>
@ -390,7 +338,7 @@ server and the file-based help entries will be available to view.</p>
<h2>Entry priority<a class="headerlink" href="#entry-priority" title="Permalink to this headline"></a></h2>
<p>Should you have clashing help-entries between the three types of available
entries, the priority is</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Command</span><span class="o">-</span><span class="n">auto</span><span class="o">-</span><span class="n">help</span> <span class="o">&gt;</span> <span class="n">Db</span><span class="o">-</span><span class="n">help</span> <span class="o">&gt;</span> <span class="n">File</span><span class="o">-</span><span class="n">help</span>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Command-auto-help &gt; Db-help &gt; File-help
</pre></div>
</div>
<p>So if you create a db-help entry ‘foo’, it will replace any file-based help
@ -420,14 +368,7 @@ also not show up in the index). If <code class="docutils literal notranslate"><s
everyone can read the help entry.</p></li>
</ul>
<p>For Commands you set the help-related locks the same way you would any lock:</p>
<div class="highlight-python notranslate"><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 class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyCommand</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyCommand</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> &lt;docstring for command&gt;</span>
<span class="sd"> &quot;&quot;&quot;</span>
@ -435,21 +376,19 @@ everyone can read the help entry.</p></li>
<span class="c1"># everyone can use the command, builders can view it in the help index</span>
<span class="c1"># but only devs can actually read the help (a weird setup for sure!)</span>
<span class="n">locks</span> <span class="o">=</span> <span class="s2">&quot;cmd:all();view:perm(Builders);read:perm(Developers)</span>
</pre></div>
</td></tr></table></div>
</div>
<p>Db-help entries and File-Help entries work the same way (except the <code class="docutils literal notranslate"><span class="pre">cmd</span></code>-type
lock is not used. A file-help example:</p>
<div class="highlight-python notranslate"><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></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">help_entry</span> <span class="o">=</span> <span class="p">{</span>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">help_entry</span> <span class="o">=</span> <span class="p">{</span>
<span class="c1"># ...</span>
<span class="n">locks</span> <span class="o">=</span> <span class="s2">&quot;read:perm(Developer)&quot;</span><span class="p">,</span>
<span class="c1"># ...</span>
<span class="p">}</span>
</pre></div>
</td></tr></table></div>
</div>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 1.0: </span>Changed the old ‘view’ lock to control the help-index inclusion and added
the new ‘read’ lock-type to control access to the entry itself.</p>
@ -458,7 +397,7 @@ the new ‘read’ lock-type to control access to the entry itself.</p>
<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>
<a class="reference internal" href="../api/evennia.commands.default.help.html#evennia.commands.default.help.CmdHelp" title="evennia.commands.default.help.CmdHelp"><span class="xref myst py py-class">evennia.commands.default.help.CmdHelp</span></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
@ -546,7 +485,7 @@ at that point).</p>
<h3>Versions</h3>
<ul>
<li><a href="Help-System.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
<li><a href="../../0.95/index.html">0.95 (v0.9.5 branch)</a></li>
</ul>
</div>