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.

docs/sphinx/source/wiki/CommandPrompt.rst

@@ -0,0 +1,85 @@
+Adding a command prompt
+=======================
+
+A *prompt* is quite common in MUDs. The prompt display useful details
+about your character that you are likely to want to keep tabs on at all
+times, such as health, magical power etc. It might also show things like
+in-game time, weather and so on.
+
+Prompt after the command
+------------------------
+
+The easiest form of prompt is one that is sent after every command you
+send. So, say you enter the look command; you would then get the result
+of the look command, followed by the prompt. As an example:
+
+::
+
+    > look You see nothing special. HP:10, SP:20, MP: 5
+
+MUD clients can be set to detect prompts like this and display them in
+various client-specific ways.
+
+To add this kind of "after-every-command-prompt", you can use the
+``at_post_cmd()`` hook. This is to be defined on the Command class and
+Evennia will always call it right after ``func()`` has finished
+executing. For this to appear after every command you enter, it's best
+to put this in the parent for your commands (for the default commands
+this would be ``MuxCommand``), but you could also put it only in certain
+commands (might not be too useful to show it if you are doing game
+administration for example).
+
+::
+
+    class MyCommand(Command):    [...]    def at_post_cmd(self):              # we assume health/stamina/magic are just stored         # as simple attributes on the character.         hp = self.caller.db.hp         sp = self.caller.db.sp         mp = self.caller.db.mp        self.caller.msg("HP: %i, SP: %i, MP: %i" % (hp, sp, mp))
+
+Prompt on the same line
+-----------------------
+
+Another, more advanced type of prompt is one that appears before the
+return of every command, on the same line:
+
+::
+
+    > look HP: 10, SP:20, MP:5 -- You see nothing special.
+
+Now, there is an ``at_pre_cmd()`` hook analogous to the hook from last
+section except called just *before* parsing of the command. But putting
+prompt code in that would just have the prompt appear on the *line
+before* the function return:
+
+::
+
+    > look HP:10, SP:20, MP: 5  You see nothing special.
+
+... which might be cool too, but not what we wanted. To have the prompt
+appear on the same line as the return this, we need to change how
+messages are returned to the player. This means a slight modification to
+our *Character class* (see `here <Objects#Characters.html>`_ on how to
+change the default Character class to your custom one). Now, all
+commands use the ``object.msg()`` method for communicating with the
+player. This is defined in ``src/objects/models.py``, on the
+``ObjectDB`` base class. This is how the ``msg()`` method is defined:
+
+::
+
+    def msg(self, outgoing_message, from_obj=None, data=None):     ...
+
+The only argument we are interested in here is the ``outgoing_message``,
+which contains the text that is about to be passed on to the player. We
+want to make sure that ``msg()`` always tack our prompt in front of the
+``outgoing_message`` before sending it on. This is done by simply
+overloading the ``msg()`` method in our custom Character class. On your
+custom Character typeclass add this:
+
+::
+
+    def msg(self, outgoing_message, from_obj=None, data=None):         # prepend the prompt in front of the message    hp = self.db.hp     sp = self.db.sp     mp = self.db.mp      prompt = "%i, %i, %i -- " % (hp, sp, mp)     outgoing_message = prompt + outgoing_message    # pass this on to the original msg() method on the database object    self.dbobj.msg(outgoing_message, from_obj=from_obj, data=data)
+
+Note that this solution will *always* give you the prompt, also if you
+use admin commands, which could get annoying. You might want to have
+some attribute defined on your character for turning on/off the prompt
+(the msg() method could look for it to determine if it should add the
+prompt or not). You can of course also name the above method
+``msg_prompt()`` and make sure that only commands that *should* return a
+prompt call this version.