More docstring

8 more files docstringed. A bit from everywere...

evennia/contrib/email_login.py

@@ -4,7 +4,7 @@ Email-based login system
 Evennia contrib - Griatch 2012
 
 
-This is a variant of the login system that requires a email-adress
+This is a variant of the login system that requires an email-address
 instead of a username to login.
 
 This used to be the default Evennia login before replacing it with a
@@ -14,16 +14,18 @@ on it. The email is not strictly needed internally, nor is any
 confirmation email sent out anyway).
 
 
-Install is simple:
+Installation is simple:
 
 To your settings file, add/edit the line:
 
+```python
 CMDSET_UNLOGGEDIN = "contrib.email-login.UnloggedinCmdSet"
+```
 
 That's it. Reload the server and try to log in to see it.
 
 The initial login "graphic" will still not mention email addresses
-after this change. The login splash screen is taken from strings in
+after this change. The login splashscreen is taken from strings in
 the module given by settings.CONNECTION_SCREEN_MODULE.
 
 """
@@ -71,8 +73,8 @@ class CmdUnconnectedConnect(MuxCommand):
     def func(self):
         """
         Uses the Django admin api. Note that unlogged-in commands
-        have a unique position in that their func() receives
+        have a unique position in that their `func()` receives
-        a session object instead of a source_object like all
+        a session object instead of a `source_object` like all
         other types of logged-in commands (this is because
         there is no object yet before the player has logged in)
         """
@@ -261,7 +263,7 @@ its and @/./+/-/_ only.") # this echoes the restrictions made by django's auth m
 
 class CmdUnconnectedQuit(MuxCommand):
     """
-    We maintain a different version of the quit command
+    We maintain a different version of the `quit` command
     here for unconnected players for the sake of simplicity. The logged in
     version is a bit more complicated.
     """
@@ -278,7 +280,7 @@ class CmdUnconnectedQuit(MuxCommand):
 
 class CmdUnconnectedLook(MuxCommand):
     """
-    This is an unconnected version of the look command for simplicity.
+    This is an unconnected version of the `look` command for simplicity.
 
     This is called by the server and kicks everything in gear.
     All it does is display the connect screen.

evennia/contrib/extended_room.py

@@ -4,7 +4,7 @@ Extended Room
 Evennia Contribution - Griatch 2012
 
 This is an extended Room typeclass for Evennia. It is supported
-by an extended Look command and an extended @desc command, also
+by an extended `Look` command and an extended `@desc` command, also
 in this module.
 
 
@@ -13,17 +13,17 @@ Features:
 1) Time-changing description slots
 
 This allows to change the full description text the room shows
-depending on larger time variations. Four seasons - spring, summer,
+depending on larger time variations. Four seasons (spring, summer,
-autumn and winter are used by default). The season is calculated
+autumn and winter) are used by default. The season is calculated
 on-demand (no Script or timer needed) and updates the full text block.
 
 There is also a general description which is used as fallback if
 one or more of the seasonal descriptions are not set when their
 time comes.
 
-An updated @desc command allows for setting seasonal descriptions.
+An updated `@desc` command allows for setting seasonal descriptions.
 
-The room uses the evennia.utils.gametime.GameTime global script. This is
+The room uses the `evennia.utils.gametime.GameTime` global script. This is
 started by default, but if you have deactivated it, you need to
 supply your own time keeping mechanism.
 
@@ -32,20 +32,20 @@ supply your own time keeping mechanism.
 
 Within each seasonal (or general) description text, you can also embed
 time-of-day dependent sections. Text inside such a tag will only show
-during that particular time of day. The tags looks like <timeslot> ...
+during that particular time of day. The tags looks like `<timeslot> ...
-</timeslot>. By default there are four timeslots per day - morning,
+</timeslot>`. By default there are four timeslots per day - morning,
 afternoon, evening and night.
 
 
 3) Details
 
 The Extended Room can be "detailed" with special keywords. This makes
-use of a special Look command. Details are "virtual" targets to look
+use of a special `Look` command. Details are "virtual" targets to look
 at, without there having to be a database object created for it. The
 Details are simply stored in a dictionary on the room and if the look
-command cannot find an object match for a "look <target>" command it
+command cannot find an object match for a `look <target>` command it
 will also look through the available details at the current location
-if applicable. An extended @desc command is used to set details.
+if applicable. An extended `@desc` command is used to set details.
 
 
 4) Extra commands
@@ -53,17 +53,17 @@ if applicable. An extended @desc command is used to set details.
   CmdExtendedLook - look command supporting room details
   CmdExtendedDesc - @desc command allowing to add seasonal descs and details,
                     as well as listing them
-  CmdGameTime     - A simple "time" command, displaying the current
+  CmdGameTime     - A simple `time` command, displaying the current
                     time and season.
 
 
 Installation/testing:
 
-1) Add CmdExtendedLook, CmdExtendedDesc and CmdGameTime to the default cmdset
+1) Add `CmdExtendedLook`, `CmdExtendedDesc` and `CmdGameTime` to the default `cmdset`
-   (see wiki how to do this).
+   (see Wiki for how to do this).
-2) @dig a room of type contrib.extended_room.ExtendedRoom (or make it the
+2) `@dig` a room of type `contrib.extended_room.ExtendedRoom` (or make it the
    default room type)
-3) Use @desc and @detail to customize the room, then play around!
+3) Use `@desc` and `@detail` to customize the room, then play around!
 
 """
 
@@ -102,7 +102,7 @@ DAY_BOUNDARIES = (0, 6 / 24.0, 12 / 24.0, 18 / 24.0)
 
 class ExtendedRoom(DefaultRoom):
     """
-    This room implements a more advanced look functionality depending on
+    This room implements a more advanced `look` functionality depending on
     time. It also allows for "details", together with a slightly modified
     look command.
     """
@@ -126,7 +126,7 @@ class ExtendedRoom(DefaultRoom):
 
     def get_time_and_season(self):
         """
-        Calculate the current time and season ids
+        Calculate the current time and season ids.
         """
         # get the current time as parts of year and parts of day
         # returns a tuple (years,months,weeks,days,hours,minutes,sec)
@@ -158,7 +158,7 @@ class ExtendedRoom(DefaultRoom):
 
     def replace_timeslots(self, raw_desc, curr_time):
         """
-        Filter so that only time markers <timeslot>...</timeslot> of the
+        Filter so that only time markers `<timeslot>...</timeslot>` of the
         correct timeslot remains in the description.
         """
         if raw_desc:
@@ -173,8 +173,8 @@ class ExtendedRoom(DefaultRoom):
         """
         This will attempt to match a "detail" to look for in the room. A detail
         is a way to offer more things to look at in a room without having to
-        add new objects. For this to work, we require a custom look command that
+        add new objects. For this to work, we require a custom `look` command that
-        allows for "look <detail>" - the look command should defer to this
+        allows for `look <detail>` - the look command should defer to this
         method on the current location (if it exists) before giving up on
         finding the target.
 
@@ -298,36 +298,39 @@ class CmdExtendedLook(default_cmds.CmdLook):
 
 class CmdExtendedDesc(default_cmds.CmdDesc):
     """
-    @desc - describe an object or room
+    `@desc` - describe an object or room.
 
     Usage:
       @desc[/switch] [<obj> =] <description>
       @detail[/del] [<key> = <description>]
 
 
-    Switches for @desc:
+    Switches for `@desc`:
-      spring  - set description for <season> in current room
+      spring  - set description for <season> in current room.
       summer
       autumn
       winter
 
-    Switch for @detail:
+    Switch for `@detail`:
-      del   - delete a named detail
+      del   - delete a named detail.
 
     Sets the "desc" attribute on an object. If an object is not given,
     describe the current room.
 
-    The alias @detail allows to assign a "detail" (a non-object
+    The alias `@detail` allows to assign a "detail" (a non-object
-    target for the look command) to the current room (only).
+    target for the `look` command) to the current room (only).
 
     You can also embed special time markers in your room description, like this:
-      <night>In the darkness, the forest looks foreboding.</night>. Text
-    marked this way will only display when the server is truly at the given
-    time slot. The available times
-    are night, morning, afternoon and evening.
 
-    Note that @detail, seasons and time-of-day slots only works on rooms in this
+        ```
-    version of the @desc command.
+        <night>In the darkness, the forest looks foreboding.</night>.
+        ```
+
+    Text marked this way will only display when the server is truly at the given
+    timeslot. The available times are night, morning, afternoon and evening.
+
+    Note that `@detail`, seasons and time-of-day slots only works on rooms in this
+    version of the `@desc` command.
 
     """
     aliases = ["@describe", "@detail"]

evennia/contrib/lineeditor.py

@@ -9,17 +9,17 @@ in-game. The editor mimics the command mechanisms of the VI editor as
 far as possible.
 
 Features of the editor:
- undo/redo
+    undo/redo.
- edit/replace on any line of the buffer
+    edit/replace on any line of the buffer.
- search&replace text anywhere in buffer
+    search&replace text anywhere in buffer.
- formatting of buffer, or selection, to certain width + indentations
+    formatting of buffer, or selection, to certain width + indentations.
- allow to echo the input or not depending on your client.
+    allow to echo the input or not, depending on your client.
 
 
 Whereas the editor is intended to be called from other commands that
 requires more elaborate text editing of data, there is also a
 stand-alone editor command for editing Attributes at the end of this
-module. To use it just import and add it to your default cmdset.
+module. To use it just import and add it to your default `cmdset`.
 
 """
 
@@ -53,9 +53,9 @@ class CmdEditorBase(Command):
 
         Where all arguments are optional.
             li  - line number (int), starting from 1. This could also
-                be a range given as <l>:<l>
+                  be a range given as <l>:<l>.
             w   - word(s) (string), could be encased in quotes.
-          txt - extra text (string), could be encased in quotes
+            txt - extra text (string), could be encased in quotes.
         """
 
         linebuffer = []
@@ -152,7 +152,9 @@ class CmdLineInput(CmdEditorBase):
     aliases = [CMD_NOINPUT]
 
     def func(self):
-        "Adds the line without any formatting changes."
+        """
+        Adds the line without any formatting changes.
+        """
         # add a line of text
         if not self.editor.buffer:
             buf = self.args
@@ -406,23 +408,23 @@ class LineEditor(object):
                  quitfunc=None, quitfunc_args=None,
                  key=""):
         """
-        caller - who is using the editor
+        caller - who is using the editor.
 
-        loadfunc - this will be called as func(*loadfunc_args) when the
+        loadfunc - this will be called as `func(*loadfunc_args)` when the
                    editor is first started, e.g. for pre-loading text into it.
-        loadfunc_args - optional tuple of arguments to supply to loadfunc.
+        loadfunc_args - optional tuple of arguments to supply to `loadfunc`.
-        savefunc - this will be called as func(*savefunc_args) when the
+        savefunc - this will be called as `func(*savefunc_args)` when the
                    save-command is given and is used to actually determine
-                   where/how result is saved. It should return True if save
+                   where/how result is saved. It should return `True` if save
                    was successful and also handle any feedback to the user.
-        savefunc_args - optional tuple of arguments to supply to savefunc.
+        savefunc_args - optional tuple of arguments to supply to `savefunc`.
-        quitfunc - this will optionally e called as func(*quitfunc_args) when
+        quitfunc - this will optionally be called as `func(*quitfunc_args)`
-                   the editor is exited. If defined, it should handle all
+                   when the editor is exited. If defined, it should handle
-                   wanted feedback to the user.
+                   all wanted feedback to the user.
-        quitfunc_args - optional tuple of arguments to supply to quitfunc.
+        quitfunc_args - optional tuple of arguments to supply to `quitfunc`.
 
         key = an optional key for naming this session (such as which attribute
-              is being edited)
+              is being edited).
         """
         self.key = key
         self.caller = caller
@@ -492,7 +494,9 @@ class LineEditor(object):
             self.unsaved = True
 
     def quit(self):
-        "Cleanly exit the editor."
+        """
+        Cleanly exit the editor.
+        """
         if self.quitfunc:
             # call quit function hook if available
             try:
@@ -549,7 +553,7 @@ class LineEditor(object):
         """
         This displays the line editor buffer, or selected parts of it.
 
-        If buf is set and is not the full buffer, offset should define
+        If `buf` is set and is not the full buffer, `offset` should define
         the starting line number, to get the linenum display right.
         """
         if buf == None:
@@ -626,7 +630,7 @@ class LineEditor(object):
 
 class CmdEditor(Command):
     """
-    start editor
+    Start editor
 
     Usage:
         @editor <obj>/<attr>

evennia/game_template/commands/command.py

@@ -13,9 +13,9 @@ class Command(BaseCommand):
     """
     Inherit from this if you want to create your own
     command styles. Note that Evennia's default commands
-    use MuxCommand instead (next in this module)
+    use MuxCommand instead (next in this module).
 
-    Note that the class's __doc__ string (this text) is
+    Note that the class's `__doc__` string (this text) is
     used by Evennia to create the automatic help entry for
     the command, so make sure to document consistently here.
 
@@ -38,15 +38,15 @@ class Command(BaseCommand):
 
     def at_pre_cmd(self):
         """
-        This hook is called before self.parse() on all commands
+        This hook is called before `self.parse()` on all commands.
         """
         pass
 
     def parse(self):
         """
-        This method is called by the cmdhandler once the command name
+        This method is called by the `cmdhandler` once the command name
         has been identified. It creates a new set of member variables
-        that can be later accessed from self.func() (see below)
+        that can be later accessed from `self.func()` (see below).
 
         The following variables are available to us:
            # class variables:
@@ -56,40 +56,40 @@ class Command(BaseCommand):
            self.locks - lock string for this command ("cmd:all()")
            self.help_category - overall category of command ("General")
 
-           # added at run-time by cmdhandler:
+           # added at run-time by `cmdhandler`:
 
            self.caller - the object calling this command
            self.cmdstring - the actual command name used to call this
                             (this allows you to know which alias was used,
                              for example)
-           self.args - the raw input; everything following self.cmdstring.
+           self.args - the raw input; everything following `self.cmdstring`.
-           self.cmdset - the cmdset from which this command was picked. Not
+           self.cmdset - the `cmdset` from which this command was picked. Not
-                         often used (useful for commands like 'help' or to
+                         often used (useful for commands like `help` or to
-                         list all available commands etc)
+                         list all available commands etc).
            self.obj - the object on which this command was defined. It is often
-                         the same as self.caller.
+                         the same as `self.caller`.
         """
         pass
 
     def func(self):
         """
         This is the hook function that actually does all the work. It is called
-         by the cmdhandler right after self.parser() finishes, and so has access
+        by the `cmdhandler` right after `self.parser()` finishes, and so has access
         to all the variables defined therein.
         """
         self.caller.msg("Command called!")
 
     def at_post_cmd(self):
         """
-        This hook is called after self.func().
+        This hook is called after `self.func()`.
         """
         pass
 
 
 class MuxCommand(default_cmds.MuxCommand):
     """
-    This sets up the basis for a Evennia's 'MUX-like' command
+    This sets up the basis for Evennia's 'MUX-like' command style.
-    style. The idea is that most other Mux-related commands should
+    The idea is that most other Mux-related commands should
     just inherit from this and don't have to implement parsing of
     their own unless they do something particularly advanced.
 
@@ -97,22 +97,22 @@ class MuxCommand(default_cmds.MuxCommand):
 
         name[ with several words][/switch[/switch..]] arg1[,arg2,...] [[=|,] arg[,..]]
 
-    The 'name[ with several words]' part is already dealt with by the
+    The `name[ with several words]` part is already dealt with by the
-    cmdhandler at this point, and stored in self.cmdname. The rest is stored
+    `cmdhandler` at this point, and stored in `self.cmdname`. The rest is stored
-    in self.args.
+    in `self.args`.
 
-    The MuxCommand parser breaks self.args into its constituents and stores them
+    The MuxCommand parser breaks `self.args` into its constituents and stores them
     in the following variables:
-      self.switches = optional list of /switches (without the /)
+        self.switches = optional list of /switches (without the /).
-      self.raw = This is the raw argument input, including switches
+        self.raw = This is the raw argument input, including switches.
-      self.args = This is re-defined to be everything *except* the switches
+        self.args = This is re-defined to be everything *except* the switches.
-      self.lhs = Everything to the left of = (lhs:'left-hand side'). If
+        self.lhs = Everything to the left of `=` (lhs:'left-hand side'). If
-                 no = is found, this is identical to self.args.
+                     no `=` is found, this is identical to `self.args`.
-      self.rhs: Everything to the right of = (rhs:'right-hand side').
+        self.rhs: Everything to the right of `=` (rhs:'right-hand side').
-                If no '=' is found, this is None.
+                    If no `=` is found, this is `None`.
-      self.lhslist - self.lhs split into a list by comma
+        self.lhslist - `self.lhs` split into a list by comma.
-      self.rhslist - list of self.rhs split into a list by comma
+        self.rhslist - list of `self.rhs` split into a list by comma.
-      self.arglist = list of space-separated args (including '=' if it exists)
+        self.arglist = list of space-separated args (including `=` if it exists).
 
     All args and list members are stripped of excess whitespace around the
     strings, but case is preserved.
@@ -121,7 +121,7 @@ class MuxCommand(default_cmds.MuxCommand):
     def func(self):
         """
         This is the hook function that actually does all the work. It is called
-        by the cmdhandler right after self.parser() finishes, and so has access
+        by the `cmdhandler` right after `self.parser()` finishes, and so has access
         to all the variables defined therein.
         """
         # this can be removed in your child class, it's just

evennia/game_template/commands/default_cmdsets.py

@@ -6,11 +6,11 @@ can be part of any number of cmdsets and cmdsets can be added/removed
 and merged onto entities at runtime.
 
 To create new commands to populate the cmdset, see
-commands/command.py.
+`commands/command.py`.
 
-This module wrap the default command sets of Evennia; overload them
+This module wraps the default command sets of Evennia; overloads them
 to add/remove commands from the default lineup. You can create your
-own cmdsets by inheriting from them or directly from evennia.CmdSet.
+own cmdsets by inheriting from them or directly from `evennia.CmdSet`.
 
 """
 
@@ -18,9 +18,9 @@ from evennia import default_cmds
 
 class CharacterCmdSet(default_cmds.CharacterCmdSet):
     """
-    The CharacterCmdSet contains general in-game commands like look,
+    The `CharacterCmdSet` contains general in-game commands like `look`,
-    get etc available on in-game Character objects. It is merged with
+    `get`, etc available on in-game Character objects. It is merged with
-    the PlayerCmdSet when a Player puppets a Character.
+    the `PlayerCmdSet` when a Player puppets a Character.
     """
     key = "DefaultCharacter"
 
@@ -37,9 +37,9 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
 class PlayerCmdSet(default_cmds.PlayerCmdSet):
     """
     This is the cmdset available to the Player at all times. It is
-    combined with the CharacterCmdSet when the Player puppets a
+    combined with the `CharacterCmdSet` when the Player puppets a
     Character. It holds game-account-specific commands, channel
-    commands etc.
+    commands, etc.
     """
     key = "DefaultPlayer"
 
@@ -56,7 +56,7 @@ class PlayerCmdSet(default_cmds.PlayerCmdSet):
 class UnloggedinCmdSet(default_cmds.UnloggedinCmdSet):
     """
     Command set available to the Session before being logged in.  This
-    holds commands like creating a new account, logging in etc.
+    holds commands like creating a new account, logging in, etc.
     """
     key = "DefaultUnloggedin"
 
@@ -82,7 +82,7 @@ class SessionCmdSet(default_cmds.SessionCmdSet):
         This is the only method defined in a cmdset, called during
         its creation. It should populate the set with command instances.
 
-        As and example we just add the empty base Command object.
+        As and example we just add the empty base `Command` object.
         It prints some info.
         """
         super(SessionCmdSet, self).at_cmdset_creation()

evennia/game_template/typeclasses/exits.py

@@ -11,24 +11,24 @@ from evennia import DefaultExit
 class Exit(DefaultExit):
     """
     Exits are connectors between rooms. Exits are normal Objects except
-    they defines the 'destination' property. It also does work in the
+    they defines the `destination` property. It also does work in the
     following methods:
 
-     basetype_setup() - sets default exit locks (to change, use at_object_creation instead)
+     basetype_setup() - sets default exit locks (to change, use `at_object_creation` instead).
      at_cmdset_get(**kwargs) - this is called when the cmdset is accessed and should
                               rebuild the Exit cmdset along with a command matching the name
-                              of the Exit object. Conventionally, a kwarg 'force_init'
+                              of the Exit object. Conventionally, a kwarg `force_init`
                               should force a rebuild of the cmdset, this is triggered
-                              by the @alias command when aliases are changed.
+                              by the `@alias` command when aliases are changed.
      at_failed_traverse() - gives a default error message ("You cannot
                             go there") if exit traversal fails and an
-                            attribute err_traverse is not defined.
+                            attribute `err_traverse` is not defined.
 
     Relevant hooks to overload (compared to other types of Objects):
-    at_before_traverse(traveller) - called just before traversing
+        at_before_traverse(traveller) - called just before traversing.
-    at_after_traverse(traveller, source_loc) - called just after traversing
+        at_after_traverse(traveller, source_loc) - called just after traversing.
         at_failed_traverse(traveller) - called if traversal failed for some reason. Will
-                                    not be called if the attribute 'err_traverse' is
+                                        not be called if the attribute `err_traverse` is
                                         defined, in which case that will simply be echoed.
     """
     pass

evennia/game_template/world/batch_cmds.ev

@@ -14,13 +14,13 @@
 # - every command must be separated by at least one line of comment.
 #
 # All supplied commands are given as normal, on their own line
-# and accepts arguments in any format up until the first next
+# and accept arguments in any format up until the first next
 # comment line begins. Extra whitespace is removed; an empty
 # line in a command definition translates into a newline.
 # 
-# See evennia/contrib/tutorial_examples/batch_cmds.ev for
+# See `evennia/contrib/tutorial_examples/batch_cmds.ev` for
 # an example of a batch-command code. See also the batch-code
-# system for loading python-code in this way.
+# system for loading python-code this way.
 #
 
 

evennia/game_template/world/prototypes.py

@@ -2,7 +2,7 @@
 Prototypes
 
 A prototype is a simple way to create individualized instances of a
-given Typeclass. For example, you might have a Sword typeclass that
+given `Typeclass`. For example, you might have a Sword typeclass that
 implements everything a Sword would need to do. The only difference
 between different individual Swords would be their key, description
 and some Attributes. The Prototype system allows to create a range of
@@ -12,27 +12,27 @@ Sabres and all Broadswords some common properties). Note that bigger
 variations, such as custom commands or functionality belong in a
 hierarchy of typeclasses instead.
 
-Example prototypes are read by the @spawn command but is also easily
+Example prototypes are read by the `@spawn` command but is also easily
-available to use from code via evennia.spawn or evennia.utils.spawner.
+available to use from code via `evennia.spawn` or `evennia.utils.spawner`.
 Each prototype should be a dictionary. Use the same name as the
 variable to refer to other prototypes.
 
 Possible keywords are:
-    prototype - string pointing to parent prototype of this structure
+    prototype - string pointing to parent prototype of this structure.
-    key - string, the main object identifier
+    key - string, the main object identifier.
-    typeclass - string, if not set, will use settings.BASE_OBJECT_TYPECLASS
+    typeclass - string, if not set, will use `settings.BASE_OBJECT_TYPECLASS`.
-    location - this should be a valid object or #dbref
+    location - this should be a valid object or #dbref.
-    home - valid object or #dbref
+    home - valid object or #dbref.
-    destination - only valid for exits (object or dbref)
+    destination - only valid for exits (object or dbref).
 
-    permissions - string or list of permission strings
+    permissions - string or list of permission strings.
-    locks - a lock-string
+    locks - a lock-string.
-    aliases - string or list of strings
+    aliases - string or list of strings.
 
-    ndb_<name> - value of a nattribute (the "ndb_" part is ignored)
+    ndb_<name> - value of a nattribute (the "ndb_" part is ignored).
     any other keywords are interpreted as Attributes and their values.
 
-See the @spawn command and evennia.utils.spawner for more info.
+See the `@spawn` command and `evennia.utils.spawner` for more info.
 
 """