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/ExecutePythonCode.rst

@@ -0,0 +1,137 @@
+<wiki:toc max\_depth
+
+"3" />
+======
+
+The ``@py`` command =
+
+The ``@py`` command supplied with the default command set of Evennia
+allows you to execute Python commands directly from inside the game. An
+alias to ``@py`` is simply "``!``". *Access to the ``@py`` command
+should be severely restricted only to game admins.* Being able to
+execute arbitrary Python code on the server is not something you should
+entrust to just anybody.
+
+::
+
+    @py 1+2  <<< 3
+
+Available variables
+-------------------
+
+A few local variables are made available when running ``@py``. These
+offer entry into the running system and allows for quick exploration of
+the standard objects.
+
+-  **self** / **me** - the calling object (i.e. you)
+-  **here** - the current caller's location
+-  **obj** - a dummy `Object <Objects.html>`_ instance
+-  **script** - a dummy `Script <Scripts.html>`_ instance
+-  **config** - a dummy ConfigValue instance
+-  **ObjectDB** - direct reference to the ObjectDB database class
+-  **ScriptDB** - direct reference to the ScriptDB database class
+-  **!ConfigValue** - direct reference to the ConfigValue database class
+
+Returning output
+----------------
+
+This is an example where we import and test one of Evennia's utilities
+found in ``src/utils/utils.py``:
+
+::
+
+    @py from src.utils import utils; utils.time_format(33333) <<< Done.
+
+Note that we didn't get any return value, all we where told is that the
+code finished executing without error. This is often the case in more
+complex pieces of code which has no single obvious return value. To see
+the output from the ``time_format()`` function we need to tell the
+system to echo it to us explicitly with ``self.msg()``.
+
+::
+
+    @py from src.utils import utils; self.msg(utils.time_format(33333)) 09:15 <<< Done.
+
+If you were to use Python's standard ``print``, you will see the result
+in your current ``stdout`` (your terminal by default), *if* you are
+running Evennia in *interactive mode* (with the ``-i`` flag).
+
+Finding objects
+---------------
+
+A common use for ``@py`` is to explore objects in the database, for
+debugging and performing specific operations that are not covered by a
+particular command.
+
+Locating an object is best done using ``self.search()``:
+
+::
+
+    @py self.search("red_ball") <<< Ball @py self.search("red_ball").db.color = "red" <<< Done. @py self.search("red_ball").db.color <<< red
+
+``self.search()`` is by far the most used case, but you can also search
+other database tables for other Evennia entities like scripts or
+configuration entities. To do this you can use the generic search
+entries found in ``src.utils.search``.
+
+::
+
+    @py from src.utils import search; self.msg(search.scripts("sys_game_time")) <<< [<src.utils.gametime.GameTime object at 0x852be2c>]
+
+You can also use the database model managers directly (accessible
+through the ``objects`` properties of database models). This is a bit
+more flexible since it gives you access to the full range of database
+search methods defined in each manager.
+
+::
+
+    @py ScriptDB.objects.script_search("sys_game_time") <<< [<src.utils.gametime.GameTime object at 0x852be2c>]
+
+(Note that since this second example becomes a simple statement, we
+don't have to wrap it in ``self.msg()`` to get the output). If you want
+to see what is available, the managers are found in the ``manager.py``
+files throughout the ``src`` directory (e.g.
+``src/objects/manager.py``). Through the manager you can also view the
+contents of the database using normal Django query operations:
+
+::
+
+    @py ConfigValue.objects.all() <<< [<ConfigValue: default_home]>, <ConfigValue:site_name>, ...]
+
+In doing so however, keep in mind the difference between `Typeclasses
+and Database Objects <Typeclasses.html>`_: Using the search commands in
+the managers will return *!TypeClasses*. Using Django's default search
+methods (``get``, ``filter`` etc) will return *Database objects*. This
+distinction can often be disregarded, but as a convention you should try
+to stick with the manager search functions and work with TypeClasses in
+most situations.
+
+::
+
+    # this uses Evennia's manager method get_id().  # It returns a Character typeclass instance @py ObjectDB.objects.get_id(1).__class__ <<< Character# this uses the standard Django get() query.  # It returns a django database model instance. @py ObjectDB.objects.get(id=1).__class__ <<< <class 'src.objects.models.ObjectDB'>
+
+Running a Python Parser outside the game
+========================================
+
+``@py`` has the advantage of operating inside a running server, where
+you can test things in real time. Much of this *can* be done from the
+outside too though.
+
+Go to the ``game`` directory and get into a new terminal.
+
+::
+
+    python manage.py shell
+
+Your default Python intrepeter will start up, configured to be able to
+work with and import all modules of your Evennia installation. From here
+you can explore the database and test-run individual modules as desired.
+Not only does a fully featured Python interpreter like
+`iPython <http://ipython.scipy.org/moin/>`_ allow you to work over
+several lines, it also has lots of other editing features, usch as
+tab-completion and ``__doc__``-string reading.
+
+::
+
+    $ python manage.py shellIPython 0.10 -- An enhanced Interactive Python ...In [1]: from src.objects.models import ObjectDB In [2]: ObjectDB.objects.all() Out[3]: [<ObjectDB: Harry>, <ObjectDB: Limbo>, ...]
+