Updated ReST documentation

docs/sphinx/source/conf.py

@@ -52,9 +52,9 @@ copyright = u'2011, Evennia-development team'
 # built documents.
 #
 # The short X.Y version.
-version = 'Alpha'
+version = 'Beta'
 # The full version, including alpha/beta/rc tags.
-release = 'Alpha'
+release = 'Beta'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/sphinx/source/wiki/Contributing.rst

@@ -22,7 +22,8 @@ improving things.
 
 The most elegant way to contribute code to Evennia is to use Mercurial
 to create an online *clone* of the Evennia repository and make your
-changes to that. .
+changes to that. Here's how to create your own clone (you only need to
+do this once):
 
 #. Go to the
    `Checkout <http://code.google.com/p/evennia/source/checkout>`_ page.
@@ -33,18 +34,22 @@ changes to that. .
    like "my repo for contributing to Evennia". Accept.
 #. Your new repo is created. You should see it appear in the `clone-repo
    list <https://code.google.com/p/evennia/source/clones.html>`_. This
-   is actually your own mini-version of the Evennia page! Choose your
-   repo and you will find it has its own Checkout page. Use the command
-   there to get a local copy of your clone to your computer.
+   is actually your own mini-version of the Evennia page!
+#. Choose your repo and you will find it has its own Checkout page. Use
+   the command shown there to get a local copy of your clone to your
+   computer.
+
+Once you have an online clone and a local copy of it:
+
 #. Code away on your computer, fixing bugs or whatnot (you can be
    offline for this). Commit your code to your local clone as you work,
    as often as you like.
 #. When you have something you feel is worthwhile (or just want to ask
    people's opinions or make an online backup), *push* your local code
    up to your online repository with Mercurial.
-#. Let people know what you did, talk discuss. If you think your changes
-   should be merged into main Evennia (maybe you have made bugfixes,
-   added new features etc), make a new
+#. Let people know what you did - talk and discuss. If you think your
+   changes should be merged into main Evennia (maybe you have made
+   bugfixes, added new features etc), make a new
    `Issue <http://code.google.com/p/evennia/issues/list>`_ using the
    "Merge Request" template. Try to separate features with different
    commits, so it's possible to pick individual features.
@@ -58,8 +63,18 @@ Contributing with Patches
 To help with Evennia development it's recommended to do so using a clone
 repository as described above. But for small, well isolated fixes you
 are also welcome to submit your suggested Evennia fixes/addendums as
-`patches <https://secure.wikimedia.org/wikipedia/en/wiki/Patch_(computing).html>`_
-if you like. Depending on what fits best, post your patch to the `issue
+*patches*. You can use normal
+`patches <https://secure.wikimedia.org/wikipedia/en/wiki/Patch_(computing).html>`_,
+but it might be easier to use mercurial's own patch mechanism. Make sure
+you have committed your latest fixes first, then
+
+::
+
+    hg export tip > mypatch.patch
+
+This will create a patch file ``mypatch.patch`` that can be imported by
+others with ``hg import mypatch.patch``. Depending on what fits best,
+post your patch to the `issue
 tracker <https://code.google.com/p/evennia/issues/list.html>`_ or to the
 `discussion
 forum <https://groups.google.com/forum/#!forum/evennia.html>`_. Please

docs/sphinx/source/wiki/DeveloperCentral.rst

@@ -3,12 +3,21 @@ Developer Central
 
 This page serves as a central nexus for useful information regarding
 coding using the Evennia codebase, and also for development of the
-codebase itself. Everyone is welcome to help out! If you have any
-questions, please feel free to ask them in the `Forum/Discussion
-Group <http://www.evennia.com/discussions>`_. Bugs should be reported to
-the `Issue tracker <http://code.google.com/p/evennia/issues/list>`_. You
-can find more links to Evennia resources from the `Links <Links.html>`_
-page.
+codebase itself. Everyone is welcome to `help
+out <http://code.google.com/p/evennia/wiki/Contributing>`_! If you have
+any questions, please feel free to ask them in the `Forum/Discussion
+Group <http://www.evennia.com/discussions>`_. If you want more docs on a
+particular issue, consider filling out our
+"https://docs.google.com/spreadsheet/viewform?hl
+
+en\_US&formkey
+
+dGN0VlJXMWpCT3VHaHpscDEzY1RoZGc6MQ#gid
+======================================
+
+0.html">online form and tell us! Bugs should be reported to the `Issue
+tracker <http://code.google.com/p/evennia/issues/list>`_. You can find
+more links to Evennia resources from the `Links <Links.html>`_ page.
 
 General Evennia development information
 ---------------------------------------

docs/sphinx/source/wiki/DirectoryOverview.rst

@@ -1,7 +1,7 @@
 Evennia directory overview
 ==========================
 
-Evennia's main directory (``evennia``) is divided into four sub
+Evennia's main directory (``evennia``) is divided into five sub
 directories - ``src/``, ``game/``, ``contrib/``, ``locale`` and
 ``doc/``. The first two are the most important ones. ``game/`` is the
 place where you will create your own game, whereas ``src/`` is the home
@@ -19,15 +19,18 @@ binary versions of the ``.py`` files to speed up execution.
 The ``docs/`` directory
 -----------------------
 
-You may have noticed that ``docs/`` is pretty empty. This is because you
-are in fact reading the docs right now - this wiki *is* the
-documentation.
+This contains Evennia's offline documentation. The main source of
+up-to-date documentation is the online wiki however.
 
-You can create the *autodocs* of Evennia by following the instructions
-in ``docs/README``. This will make use of the source code itself to
+Read ``sphinx/README`` for instructions on building the ReST
+documentation, based on a current snapshot of the wiki. This can be
+browsed offline or made into a PDF for printing etc.
+
+You can create the Evennia *autodocs* by following the instructions in
+``doxygen/README``. This will make use of the source code itself to
 create a nice browsable web-index of all the sources and comments. In
 the same way you could in theory also create nice ``LaTeX``-formatted
-PDFs of the Evennia source (all 300+ pages of it ...).
+PDFs of the Evennia source (all 400+ pages of it ...).
 
 The ``locale`` directory
 ------------------------

docs/sphinx/source/wiki/HowToGetAndGiveHelp.rst

@@ -6,6 +6,18 @@ How to *get* Help
 If you cannot find what you are looking for in the `online
 documentation <Index.html>`_, here's what to do:
 
+-  If you don't understand a concept or think the docs are not clear
+   enough, fill in our quick little
+   "https://docs.google.com/spreadsheet/viewform?hl
+
+   en*US&formkey*
+
+   dGN0VlJXMWpCT3VHaHpscDEzY1RoZGc6MQ#gid
+   ======================================
+
+   0.html">online form and say so - maybe the docs need to be improved
+   or a tutorial added!
+
 -  If you have trouble with a missing feature or a problem you think is
    a bug, go to the `issue
    tracker <http://code.google.com/p/evennia/issues/list>`_. If you
@@ -19,7 +31,7 @@ documentation <Index.html>`_, here's what to do:
 -  If you want more direct discussions with developers and other users,
    consider dropping into our IRC chat channel
    "http://webchat.freenode.net/?channels
-   evennia">#evennia on the *Freenode* network. Please note however that
+   evennia">#evennia on the Freenode\_ network. Please note however that
    you have to be patient if you don't get any response immediately; we
    are all in very different time zones and many have busy personal
    lives. So you might have to lurk about for a while - you'll get

docs/sphinx/source/wiki/Index.rst

@@ -3,6 +3,16 @@ Evennia Documentation
 
 This is Evennia's manual. You should hopefully find all you need to know
 about coding with, extending and using the codebase among these pages.
+If you have trouble with unclear documentation, fill in our quick
+"https://docs.google.com/spreadsheet/viewform?hl
+
+en\_US&formkey
+
+dGN0VlJXMWpCT3VHaHpscDEzY1RoZGc6MQ#gid
+======================================
+
+0.html">online form and tell us so - maybe more details or a new
+tutorial is needed!
 
 The documentation is divided into several main categories. If you are
 new, it might be an idea to browse the sections in the order they are

docs/sphinx/source/wiki/Locks.rst

@@ -167,7 +167,7 @@ You are not allowed to use just any function in your lock definition;
 you are infact only allowed to use those functions defined in one of the
 modules given in ``settings.LOCK_FUNC_MODULES``. All functions in any of
 those modules will automatically be considered a valid lock function.
-The default ones are found in src/locks/lockfuncs.py.
+The default ones are found in ``src/locks/lockfuncs.py``.
 
 A lock function must always accept at least two arguments - the
 *accessing object* (this is the object wanting to get access) and the
@@ -185,11 +185,11 @@ appear as extra arguments.
         return False
 
 (Using the ``*`` and ``**`` syntax causes Python to magically put all
-extra arguments into a list ``args``and all keyword arguments into a
+extra arguments into a list ``args`` and all keyword arguments into a
 dictionary ``kwargs`` respectively. If you are unfamiliar with how
 ``*args`` and ``**kwargs`` work, see the Python manuals).
 
-Some useful default lockfuncs (see lockfuncs.py for a full list):
+Some useful default lockfuncs (see ``src/locks/lockfuncs.py`` for more):
 
 -  ``true()/all()`` - give access to everyone
 -  ``false()/none()/superuser()`` - give access to noone. Superusers
@@ -226,8 +226,8 @@ like rooms and exits store their internal variables). This is called
 once, before ``at_object_creation``, so just put them in the latter
 method on your child object to change the default. Also creation
 commands like ``@create`` changes the locks of objects you create - for
-example it sets the ``control`` lock\_type allow youm, its creator to
-control and delete the object.
+example it sets the ``control`` lock\_type so as to allow you, its
+creator, to control and delete the object.
 
 Permissions
 ===========
@@ -295,11 +295,12 @@ You are only allowed to do *examine* on this object if you have
 ::
 
     # lock for the tell command
-    cmd: perm(Builders) and not perm(no_tell)
+    cmd: not perm(no_tell)
 
-Locks can be used to implement highly specific bans. Set this on e.g.
-the ``tell`` command, then give a player the "permission" ``no_tell`` to
-disable their use of this particular command henceforth.
+Locks can be used to implement highly specific bans. This will allow
+everyone *not* having the "permission" ``no_tell`` to use the ``tell``
+command. Just give a player the "permission" ``no_tell`` to disable
+their use of this particular command henceforth.
 
 ::
 

docs/sphinx/source/wiki/SessionProtocols.rst

@@ -107,10 +107,10 @@ player's client and the server on the protocol level, often due to the
 request of the player's client software rather than any sort of active
 input by the player. There are two main types:
 
--  Data requested by the client which the server responds to
+-  Data requested by the client to which the server responds
    immediately. This could for example be data that should go into a
    window that the client just opened up.
--  Data the server sends to the client to keep ut up-to-date. A common
+-  Data the server sends to the client to keep it up-to-date. A common
    example of this is something like a graphical health bar - *whenever*
    the character's health status changes the server sends this data to
    the client so it can update the bar graphic. This sending could also
@@ -150,57 +150,73 @@ Example of out-of-band calling sequence
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Let's say we want our client to be able to request the character's
-current health. In our Portal protocol we somehow parse the incoming
-data stream and figure out what the request for health looks like. We
-map this to the Evennia ``get_health`` function.
+current health, stamina and maybe some skill values. In our Portal
+protocol we somehow parse the incoming data stream and figure out what
+the request for health looks like. We map this to the Evennia
+``get_health`` function.
 
 We point ``settings.OOB_FUNC_MODULE`` to someplace in ``game/`` and
-create a module there with the following function:
+create a module there with the following functions:
 
 ::
 
-    # the caller is always added as first argument
-    # we also assume health is stored as a simple 
-    # attribute on the character here. 
-    def get_health(character):    
-        return character.db.health
+    # the caller is automatically added as first argument
+    def get_health(character):
+        "Get health, stored as simple attribute"    
+        return character.db.health 
+    def get_stamina(character):
+        "Get stamina level, stored as simple attribute"
+        return character.db.stamina
+    def get_skill(character, skillname, master=False):
+        """we assume skills are stored as a dictionary 
+           stored in an attribute. Master skills are 
+           stored separately (for whatever reason)"""
+        if master:
+            return character.db.skills_master.get(skillname, "NoSkill")
+        return character.db.skills.get(skillname, "NoSkill")
 
-Done, this function will do just what we want. Let's finish up the first
-part of the portal protocol:
+Done, the functions will return what we want assuming Characters do
+store this information in our game. Let's finish up the first part of
+the portal protocol:
 
 ::
 
     # this method could be named differently depending on the 
     # protocol you are using (this is telnet)
     def lineReceived(self, string):
-       # (does stuff to analyze the incoming string)   outdict = 
+       # (does stuff to analyze the incoming string)
+       # ...
+       outdict = 
        if GET_HEALTH:
            # call get_health(char)
            outdict["get_health"] = ([], )
-       elif GET_MANA:
+       elif GET_STAMINA:
            # call get_mana(char)
-           outdict["get_mana"] = ([], )
-       elif GET_CONFIG:
-           # call get_config(char, 2, hidden=True)
-           outdict["get_config"] = ([2], 'hidden':True)   [...]   self.sessionhandler.oob_data_out(outdict)
+           outdict["get_stamina"] = ([], )
+       elif GET_MASTER_SKILL_SMITH:
+           # call get_skill(char, "smithing", master=True)
+           outdict["get_skill"] = (["smithing"], 'master':True)   [...]   self.sessionhandler.oob_data_out(outdict)
 
-The server will properly accept this and call get\_health and get the
-right value for the health. We need to define an ``oob_data_out(data)``
-in our portal protocol to catch the return value:
+The Server will properly accept this and call the relevant functions to
+get their return values for the health, stamina and skill. The return
+values will be packed in a dictionary keyed by function name before
+being passed back to the Portal. We need to define
+``oob_data_out(data)`` in our portal protocol to catch this:
 
 ::
 
     def oob_data_out(self, data):
-        # the indata is a dicationary funcname:retval    outstring = ""
+        # the indata is a dictionary funcname:retval    outstring = ""
         for funcname, retval in data.items():
             if funcname == 'get_health':
                 # convert to the right format for sending back to client, store
                 # in outstring ...
          [...]
+        # send off using the protocols send method (this is telnet)
+        sendLine(outstring)
 
-Above, once the dict is parsed and the return values properly put in a
-format the client will understand, send the whole thing off using the
-protocol's relevant send method.
+As seen, ``oob_data`` takes the values and formats into a form the
+protocol understands before sending it off.
 
 Implementing auto-sending
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -210,9 +226,9 @@ To have the Server update the client regularly, simply create a global
 dictionary (basically faking a request from the portal) and sends it
 directly to
 ``src.server.sessionhandler.oob_data_in(session.sessid, datadict)``.
-Repeat for all sessions. All specified OOB functions are called as
-normal and data will be sent back to be handled by the portal just as if
-the portal initiated the request.
+Loop over all relevant sessions. The Server will treat this like a
+Portal call and data will be sent back to be handled by the portal as
+normal.
 
 Assorted notes
 --------------