From 3337c0f787992c405eb3d855d27b09ab0b33c143 Mon Sep 17 00:00:00 2001 From: Griatch Date: Mon, 14 Nov 2011 20:17:04 +0100 Subject: [PATCH] Updated ReST documentation --- docs/sphinx/source/conf.py | 4 +- docs/sphinx/source/wiki/Contributing.rst | 33 ++++++--- docs/sphinx/source/wiki/DeveloperCentral.rst | 21 ++++-- docs/sphinx/source/wiki/DirectoryOverview.rst | 17 +++-- .../source/wiki/HowToGetAndGiveHelp.rst | 14 +++- docs/sphinx/source/wiki/Index.rst | 10 +++ docs/sphinx/source/wiki/Locks.rst | 19 ++--- docs/sphinx/source/wiki/SessionProtocols.rst | 74 +++++++++++-------- 8 files changed, 129 insertions(+), 63 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 3309228c0a..a3e7392590 100644 --- a/docs/sphinx/source/conf.py +++ b/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. diff --git a/docs/sphinx/source/wiki/Contributing.rst b/docs/sphinx/source/wiki/Contributing.rst index 797f0d3c1c..66e5a6757d 100644 --- a/docs/sphinx/source/wiki/Contributing.rst +++ b/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 `_ 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 `_. 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 `_ 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 `_ -if you like. Depending on what fits best, post your patch to the `issue +*patches*. You can use normal +`patches `_, +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 `_ or to the `discussion forum `_. Please diff --git a/docs/sphinx/source/wiki/DeveloperCentral.rst b/docs/sphinx/source/wiki/DeveloperCentral.rst index 88f5900080..d82baf68fd 100644 --- a/docs/sphinx/source/wiki/DeveloperCentral.rst +++ b/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 `_. Bugs should be reported to -the `Issue tracker `_. You -can find more links to Evennia resources from the `Links `_ -page. +codebase itself. Everyone is welcome to `help +out `_! If you have +any questions, please feel free to ask them in the `Forum/Discussion +Group `_. 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 `_. You can find +more links to Evennia resources from the `Links `_ page. General Evennia development information --------------------------------------- diff --git a/docs/sphinx/source/wiki/DirectoryOverview.rst b/docs/sphinx/source/wiki/DirectoryOverview.rst index 20536cc309..e55cc01083 100644 --- a/docs/sphinx/source/wiki/DirectoryOverview.rst +++ b/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 ------------------------ diff --git a/docs/sphinx/source/wiki/HowToGetAndGiveHelp.rst b/docs/sphinx/source/wiki/HowToGetAndGiveHelp.rst index 7e2346eb02..3e96b4065f 100644 --- a/docs/sphinx/source/wiki/HowToGetAndGiveHelp.rst +++ b/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 `_, 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 `_. If you @@ -19,7 +31,7 @@ documentation `_, 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 diff --git a/docs/sphinx/source/wiki/Index.rst b/docs/sphinx/source/wiki/Index.rst index 042230c629..261e6b0fe7 100644 --- a/docs/sphinx/source/wiki/Index.rst +++ b/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 diff --git a/docs/sphinx/source/wiki/Locks.rst b/docs/sphinx/source/wiki/Locks.rst index c9b2b1c875..89a17a7956 100644 --- a/docs/sphinx/source/wiki/Locks.rst +++ b/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. :: diff --git a/docs/sphinx/source/wiki/SessionProtocols.rst b/docs/sphinx/source/wiki/SessionProtocols.rst index 268a89cb2a..f37bf320f8 100644 --- a/docs/sphinx/source/wiki/SessionProtocols.rst +++ b/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 --------------