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

Added Sphinx (reST-style) conversion of Evennia documentation to docs/. This is an auto-generated conversion directly from the Wiki, so it's not custom-written in any way (will also make it easy to update). You need Sphinx to compile the sources into fancy pages. Supporting sphinx is to make documentation easier to print and view offline. Currently no sphinx src-code viewing is activated by default, it gives too many spurious errors (the converters are in the repo though if you're interested in experimenting). So for offline autodocs, doxygen is still to recommend.

Browse source
This commit is contained in:
Griatch 2011-09-10 23:44:49 +02:00
parent 5a2b9e27a0
commit bd0079a39d
65 changed files with 9394 additions and 143 deletions
Download patch file Download diff file Expand all files Collapse all files

114
docs/sphinx/source/wiki/HelpSystem.rst Normal file
View file

@ -0,0 +1,114 @@
*How to use Evennia's help system*
Help system
===========
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 *auto-help* system.
Viewing the help database
-------------------------
The main command is ``help``.
::
help [searchstring]
This will show a list of help entries, ordered after categories. You
will find two sections, *Command help entries* and *Other help entries*
(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.
Command Auto-help system
------------------------
One important use of the help system is to teach the use of in-game
commands. Evennia offers a dynamically updated help system for all your
commands, new and old, known simply as the *auto-help* system. Only
commands that you can actually use are picked up by the auto-help
system. That means an admin will see a considerably larger mass of help
topics when using the ``help`` command than a normal player.
The auto-help system uses the ``__doc__`` strings of your command
definitions 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 - updating the help system is just a ``@reload`` away.
There is no need to manually create help database entries for commands;
as long as you keep the docstrings updated your help will be dynamically
updated for you as well.
Example (from a module with command definitions):
::
class CmdMyCmd(Command): """ mycmd - my very own command Usage: mycmd[/switches] <args> Switches: test - test the command run - do something else This is my own command that does things to you when you supply it with arguments. """ ... help_category = "Building" ...
So the text at the very top of the command class definition is the
class' ``__doc__``-string and what will be shown to users looking for
help. Try to use a consistent formatting between your help strings (for
example, all default commands have ``__doc__``-strings formatted in the
way seen above). You should also supply the ``help_category`` class
property if you can; this helps to group help entries together for
easier finding (if you don't supply a help\_category, "General" will be
assumed).
Other help entries (entries stored in database)
-----------------------------------------------
The *Other help* section you see when using the ``help`` command shows
all help entries that has been manually added to the database by staff.
Instead of being generated from the code by Evennia, these are stored in
the database using a model called *!HelpEntry*. HelpEntry topics are
intended for world-game-info, tutorials and other types of useful
information not directly tied to a command and covered by auto-help.
A help entry consists of four parts:
- The *topic*. 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.
- The *help category*. Examples are *Administration*, *Building*,
*Comms* or *General*. This is an overall grouping of similar help
topics, used by the engine to give a better overview.
- The *text* - the help text itself, of any length. This can also
include *markup*, see below.
- locks - a `lock definition <Locks.html>`_. Help commands check for
access\_types ``examine`` and ``edit``.
You can create new help entries in code by using
``src.utils.create.create_help_entry()``:
::
from src.utils import create entry = create.create_help_entry("emote", "Emoting is important because ...", category="Roleplaying", locks="view:all()"):
From inside the game those with the right permissions can use the
``@sethelp`` command to add and modify help entries.
::
> @sethelp/add emote = The emote command is ...
Using ``@sethelp`` you can add, delete and append text to existing
entries. By default new entries will go in the *General* help category.
You can change this using a different form of the ``@sethelp`` command:
::
> @sethelp/add emote, Roleplaying = Emoting is important because ...
If the category *Roleplaying* did not exist it is created and will
appear in the help index. You can, finally, define a lock for the help
entry by following the category with a `lock definition <Locks.html>`_:
::
> @sethelp/add emote, Roleplaying, view:all() = The emote command ...