Clean up docstrings

docs/source/Coding-Introduction.md

@@ -58,5 +58,5 @@ Some people find reading documentation extremely dull and shun it out of princip
 
 And finally, of course, have fun!
 
-[feature-request]: (https://github.com/evennia/evennia/issues/new?title=Feature+Request%3a+%3Cdescriptive+title+here%3E&body=%23%23%23%23+Description+of+the+suggested+feature+and+how+it+is+supposed+to+work+for+the+admin%2fend+user%3a%0D%0A%0D%0A%0D%0A%23%23%23%23+A+list+of+arguments+for+why+you+think+this+new+feature+should+be+included+in+Evennia%3a%0D%0A%0D%0A1.%0D%0A2.%0D%0A%0D%0A%23%23%23%23+Extra+information%2c+such+as+requirements+or+ideas+on+implementation%3a%0D%0A%0D%0A
+[feature-request]: https://github.com/evennia/evennia/issues/new?title=Feature+Request%3a+%3Cdescriptive+title+here%3E&body=%23%23%23%23+Description+of+the+suggested+feature+and+how+it+is+supposed+to+work+for+the+admin%2fend+user%3a%0D%0A%0D%0A%0D%0A%23%23%23%23+A+list+of+arguments+for+why+you+think+this+new+feature+should+be+included+in+Evennia%3a%0D%0A%0D%0A1.%0D%0A2.%0D%0A%0D%0A%23%23%23%23+Extra+information%2c+such+as+requirements+or+ideas+on+implementation%3a%0D%0A%0D%0A
 [bug]: https://github.com/evennia/evennia/issues/new?title=Bug%3a+%3Cdescriptive+title+here%3E&body=%23%23%23%23+Steps+to+reproduce+the+issue%3a%0D%0A%0D%0A1.+%0D%0A2.+%0D%0A3.+%0D%0A%0D%0A%23%23%23%23+What+I+expect+to+see+and+what+I+actually+see+%28tracebacks%2c+error+messages+etc%29%3a%0D%0A%0D%0A%0D%0A%0D%0A%23%23%23%23+Extra+information%2c+such+as+Evennia+revision%2frepo%2fbranch%2c+operating+system+and+ideas+for+how+to+solve%3a%0D%0A%0D%0A

evennia/server/portal/portalsessionhandler.py

@@ -225,16 +225,16 @@ class PortalSessionHandler(SessionHandler):
     def server_connect(self, protocol_path="", config=dict()):
         """
         Called by server to force the initialization of a new protocol
-        instance. Server wants this instance to get a unique sessid
+        instance. Server wants this instance to get a unique sessid and to be
-        and to be connected back as normal. This is used to initiate
+        connected back as normal. This is used to initiate irc/rss etc
-        irc/rss etc connections.
+        connections.
 
         Args:
-            protocol_path (st): Full python path to the class factory
+            protocol_path (str): Full python path to the class factory
                 for the protocol used, eg
                 'evennia.server.portal.irc.IRCClientFactory'
             config (dict): Dictionary of configuration options, fed as
-                **kwarg to protocol class' __init__ method.
+                `**kwarg` to protocol class `__init__` method.
 
         Raises:
             RuntimeError: If The correct factory class is not found.

evennia/server/portal/telnet_oob.py

@@ -10,19 +10,22 @@ how and if they are handled.  Examples of OOB instructions could be to
 instruct the client to play sounds or to update a graphical health
 bar.
 
-> Note that in Evennia's Web client, all send commands are "OOB
+> Note that in Evennia's Web client, all send commands are "OOB commands",
-commands", (including the "text" one), there is no equivalence to
+ (including the "text" one), there is no equivalence to MSDP/GMCP for the
-MSDP/GMCP for the webclient since it doesn't need it.
+ webclient since it doesn't need it.
 
 This implements the following telnet OOB communication protocols:
-- MSDP (Mud Server Data Protocol), as per
-    http://tintin.sourceforge.net/msdp/
-- GMCP (Generic Mud Communication Protocol) as per
-    http://www.ironrealms.com/rapture/manual/files/FeatGMCP-txt.html#Generic_MUD_Communication_Protocol%28GMCP%29
 
-Following the lead of KaVir's protocol snippet, we first check if
+- MSDP (Mud Server Data Protocol), as per
-client supports MSDP and if not, we fallback to GMCP with a MSDP
+  http://tintin.sourceforge.net/msdp/
-header where applicable.
+- GMCP (Generic Mud Communication Protocol) as per
+  http://www.ironrealms.com/rapture/manual/files/FeatGMCP-txt.html#Generic_MUD_Communication_Protocol%28GMCP%29
+
+Following the lead of KaVir's protocol snippet, we first check if client
+supports MSDP and if not, we fallback to GMCP with a MSDP header where
+applicable.
+
+----
 
 """
 import re
@@ -156,17 +159,17 @@ class TelnetOOB(object):
         Notes:
             The output of this encoding will be
             MSDP structures on these forms:
-
+            ```
             [cmdname, [], {}]          -> VAR cmdname VAL ""
             [cmdname, [arg], {}]       -> VAR cmdname VAL arg
             [cmdname, [args],{}]       -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg ... ARRAYCLOSE
             [cmdname, [], {kwargs}]    -> VAR cmdname VAL TABLEOPEN VAR key VAL val ... TABLECLOSE
             [cmdname, [args], {kwargs}] -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg ... ARRAYCLOSE
                                            VAR cmdname VAL TABLEOPEN VAR key VAL val ... TABLECLOSE
-
+            ```
-            Further nesting is not supported, so if an array argument
+            Further nesting is not supported, so if an array argument consists
-            consists of an array (for example), that array will be
+            of an array (for example), that array will be json-converted to a
-            json-converted to a string.
+            string.
 
         """
         msdp_cmdname = "{msdp_var}{msdp_cmdname}{msdp_val}".format(
@@ -231,20 +234,24 @@ class TelnetOOB(object):
             up in the Core package, while Core package names will
             be stripped on the Evennia side.
 
+            ```
             [cmd.name, [], {}]          -> Cmd.Name
             [cmd.name, [arg], {}]       -> Cmd.Name arg
             [cmd.name, [args],{}]       -> Cmd.Name [args]
             [cmd.name, [], {kwargs}]    -> Cmd.Name {kwargs}
             [cmdname, [args, {kwargs}] -> Core.Cmdname [[args],{kwargs}]
+            ```
 
         Notes:
             There are also a few default mappings between evennia outputcmds and
             GMCP:
-                client_options -> Core.Supports.Get
+            ```
-                get_inputfuncs -> Core.Commands.Get
+            client_options -> Core.Supports.Get
-                get_value      -> Char.Value.Get
+            get_inputfuncs -> Core.Commands.Get
-                repeat         -> Char.Repeat.Update
+            get_value      -> Char.Value.Get
-                monitor        -> Char.Monitor.Update
+            repeat         -> Char.Repeat.Update
+            monitor        -> Char.Monitor.Update
+            ```
 
         """
 
@@ -281,11 +288,13 @@ class TelnetOOB(object):
             Clients should always send MSDP data on
             one of the following forms:
 
+            ```
             cmdname ''          -> [cmdname, [], {}]
             cmdname val         -> [cmdname, [val], {}]
             cmdname array       -> [cmdname, [array], {}]
             cmdname table       -> [cmdname, [], {table}]
             cmdname array cmdname table -> [cmdname, [array], {table}]
+            ```
 
             Observe that all MSDP_VARS are used to identify cmdnames,
             so if there are multiple arrays with the same cmdname
@@ -380,11 +389,13 @@ class TelnetOOB(object):
 
             The following is parsed into Evennia's formal structure:
 
+            ```
             Core.Name                         -> [name, [], {}]
             Core.Name string                  -> [name, [string], {}]
             Core.Name [arg, arg,...]          -> [name, [args], {}]
             Core.Name {key:arg, key:arg, ...} -> [name, [], {kwargs}]
             Core.Name [[args], {kwargs}]      -> [name, [args], {kwargs}]
+            ```
 
         """
         if isinstance(data, list):

evennia/server/profiling/dummyrunner_settings.py

@@ -14,7 +14,9 @@ ACTIONS - see below
 
 ACTIONS is a tuple
 
+```
 (login_func, logout_func, (0.3, func1), (0.1, func2) ... )
+```
 
 where the first entry is the function to call on first connect, with a
 chance of occurring given by CHANCE_OF_LOGIN. This function is usually
@@ -33,14 +35,15 @@ returns a string or a list of command strings to execute.  Use the
 client object for optionally saving data between actions.
 
 The client object has the following relevant properties and methods:
-  key - an optional client key. This is only used for dummyrunner output.
+
+- key - an optional client key. This is only used for dummyrunner output.
         Default is "Dummy-<cid>"
-  cid - client id
+- cid - client id
-  gid - globally unique id, hashed with time stamp
+- gid - globally unique id, hashed with time stamp
-  istep - the current step
+- istep - the current step
-  exits - an empty list. Can be used to store exit names
+- exits - an empty list. Can be used to store exit names
-  objs - an empty list. Can be used to store object names
+- objs - an empty list. Can be used to store object names
-  counter() - returns a unique increasing id, hashed with time stamp
+- counter() - returns a unique increasing id, hashed with time stamp
               to make it unique also between dummyrunner instances.
 
 The return should either be a single command string or a tuple of
@@ -49,6 +52,8 @@ TIMESTEP with a chance given by CHANCE_OF_ACTION by in the order given
 (no randomness) and allows for setting up a more complex chain of
 commands (such as creating an account and logging in).
 
+---
+
 """
 # Dummy runner settings