changeset 50:8102f92d21b8

docstrings: fix some rst markup warnings of sphinx
author Thomas Waldmann <tw AT waldmann-edv DOT de>
date Tue, 01 Mar 2011 17:34:56 +0100
parents 5ac57ba008b5
children 0814fedc9020 5bbe341cd721
files MoinMoin/app.py MoinMoin/auth/__init__.py MoinMoin/converter/__init__.py MoinMoin/converter/creole_in.py MoinMoin/converter/docbook_in.py MoinMoin/i18n/__init__.py MoinMoin/log.py MoinMoin/mail/sendmail.py MoinMoin/search/builtin.py MoinMoin/security/__init__.py MoinMoin/security/textcha.py MoinMoin/storage/backends/fs19_logfile.py MoinMoin/storage/backends/hg.py MoinMoin/storage/backends/indexing.py MoinMoin/storage/backends/sqla.py MoinMoin/util/lock.py MoinMoin/util/paramparser.py MoinMoin/wikiutil.py
diffstat 18 files changed, 106 insertions(+), 70 deletions(-) [+]
line wrap: on
line diff
--- a/MoinMoin/app.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/app.py	Tue Mar 01 17:34:56 2011 +0100
@@ -56,8 +56,8 @@
                               into MoinMoin.
     :param warn_default: emit a warning if moin falls back to its builtin default
                          config (maybe user forgot to specify MOINCFG?)
-    :param **kwargs: if you give additional key/values here, they'll get patched
-                     into the moin configuration class (before it instance is created)
+    :param kwargs: if you give additional keyword args, the keys/values will get patched
+                   into the moin configuration class (before its instance is created)
     """
     clock = Clock()
     clock.start('create_app total')
--- a/MoinMoin/auth/__init__.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/auth/__init__.py	Tue Mar 01 17:34:56 2011 +0100
@@ -10,12 +10,14 @@
 
     Each authentication method is an object instance containing
     four methods:
-      * login(user_obj, **kw)
-      * logout(user_obj, **kw)
-      * request(user_obj, **kw)
-      * login_hint()
+
+      * ``login(user_obj, **kw)``
+      * ``logout(user_obj, **kw)``
+      * ``request(user_obj, **kw)``
+      * ``login_hint()``
 
     The kw arguments that are passed in are currently:
+
        attended: boolean indicating whether a user (attended=True) or
                  a machine is requesting login, multistage auth is not
                  currently possible for machine logins [login only]
@@ -37,15 +39,18 @@
     The request method is called for each request except login/logout.
 
     The 'request' and 'logout' methods must return a tuple (user_obj, continue)
-    where 'user_obj' can be
+    where 'user_obj' can be:
+
       * None, to throw away any previous user_obj from previous auth methods
       * the passed in user_obj for no changes
       * a newly created MoinMoin.user.User instance
+
     and 'continue' is a boolean to indicate whether the next authentication
     method should be tried.
 
     The 'login' method must return an instance of MoinMoin.auth.LoginReturn
-    which contains the members
+    which contains the members:
+
       * user_obj
       * continue_flag
       * multistage
@@ -97,7 +102,8 @@
     the auth item that requested the multistage login and its login method is
     called with the 'multistage' keyword parameter set to True.
 
-    Each authentication method instance must also contain the members
+    Each authentication method instance must also contain the members:
+
      * login_inputs: a list of required inputs, currently supported are
                       - 'username': username entry field
                       - 'password': password entry field
--- a/MoinMoin/converter/__init__.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/converter/__init__.py	Tue Mar 01 17:34:56 2011 +0100
@@ -8,6 +8,7 @@
 of one format.
 
 There are usually three types of converters:
+
 - Between an input format like Moin Wiki or Creole and the internal tree
   representation.
 - Between the internal tree and an output format like HTML.
--- a/MoinMoin/converter/creole_in.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/converter/creole_in.py	Tue Mar 01 17:34:56 2011 +0100
@@ -9,6 +9,7 @@
     See http://wikicreole.org/ for latest specs.
 
     Notes:
+
     * No markup allowed in headings.
       Creole 1.0 does not require us to support this.
     * No markup allowed in table headings.
--- a/MoinMoin/converter/docbook_in.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/converter/docbook_in.py	Tue Mar 01 17:34:56 2011 +0100
@@ -8,7 +8,8 @@
 Currently supports DocBook v5.
 
 Some elements of DocBook v4 specification are also supported
-for backward compatibility :
+for backward compatibility:
+
   * ulink
 """
 
--- a/MoinMoin/i18n/__init__.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/i18n/__init__.py	Tue Mar 01 17:34:56 2011 +0100
@@ -4,13 +4,13 @@
 """
 MoinMoin - i18n (internationalization) and l10n (localization) support
 
-To use this, please use exactly this line (no less, no more):
+To use this, please use exactly this line (no less, no more)::
 
-from MoinMoin.i18n import _, L_, N_
+    from MoinMoin.i18n import _, L_, N_
 
-_ == gettext
-N_ == ngettext
-L_ == lazy_gettext
+    # _ == gettext
+    # N_ == ngettext
+    # L_ == lazy_gettext
 """
 
 
--- a/MoinMoin/log.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/log.py	Tue Mar 01 17:34:56 2011 +0100
@@ -9,6 +9,7 @@
     -------
     logging must be configured VERY early, before the code in log.getLogger
     gets executed. Thus, logging is configured either by:
+
     a) an environment variable MOINLOGGINGCONF that contains the path/filename
        of a logging configuration file - this method overrides all following
        methods (except if it can't read or use that configuration, then it
@@ -26,10 +27,10 @@
     MOINLOGGINGCONF=/path/to/logging.conf
     export MOINLOGGINGCONF
 
-    Or, modify your server adaptor script (e.g. moin.cgi) to do this:
+    Or, modify your server adaptor script (e.g. moin.cgi) to do this::
 
-    from MoinMoin import log
-    log.load_config('wiki/config/logging/logfile') # XXX please fix this path!
+        from MoinMoin import log
+        log.load_config('wiki/config/logging/logfile') # XXX please fix this path!
 
     You have to fix that path to use a logging configuration matching your
     needs (we provide some examples in the path given there, it is relative to
@@ -40,10 +41,10 @@
 
     Usage (for developers)
     ----------------------
-    If you write code for moin, do this at top of your module:
+    If you write code for moin, do this at top of your module::
 
-    from MoinMoin import log
-    logging = log.getLogger(__name__)
+       from MoinMoin import log
+       logging = log.getLogger(__name__)
 
     This will create a logger with 'MoinMoin.your.module' as name.
     The logger can optionally get configured in the logging configuration.
@@ -139,6 +140,7 @@
 
 def getLogger(name):
     """ wrapper around logging.getLogger, so we can do some more stuff:
+
         - preprocess logger name
         - patch loglevel constants into logger object, so it can be used
           instead of the logging module
--- a/MoinMoin/mail/sendmail.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/mail/sendmail.py	Tue Mar 01 17:34:56 2011 +0100
@@ -23,9 +23,10 @@
 
 
 def encodeAddress(address, charset):
-    """ Encode email address to enable non ascii names
+    """
+    Encode email address to enable non ascii names
 
-    e.g. '"Jürgen Hermann" <jh@web.de>'. According to the RFC, the name
+    E.g. '"Jürgen Hermann" <jh@web.de>'. According to the RFC, the name
     part should be encoded, the address should not.
 
     :param address: email address, possibly using '"name" <address>' format
@@ -177,13 +178,17 @@
     logging.debug("Mail sent successfully")
     return (1, _("Mail sent successfully"))
 
+
 def encodeSpamSafeEmail(email_address, obfuscation_text=''):
-    """ Encodes a standard email address to an obfuscated address
+    """
+    Encodes a standard email address to an obfuscated address
+
     :param email_address: mail address to encode.
-                          Known characters and their all-uppercase words translation:
-                          "." -> " DOT "
-                          "@" -> " AT "
-                          "-" -> " DASH "
+                          Known characters and their all-uppercase words translation::
+
+                              "." -> " DOT "
+                              "@" -> " AT "
+                              "-" -> " DASH "
     :param obfuscation_text: optional text to obfuscate the email.
                              All characters in the string must be alphabetic
                              and they will be added in uppercase.
--- a/MoinMoin/search/builtin.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/search/builtin.py	Tue Mar 01 17:34:56 2011 +0100
@@ -32,11 +32,12 @@
     """
     Represents a locked on-disk queue with jobs for the xapian indexer
 
-    Each job is a tuple like: (PAGENAME, ATTACHMENTNAME, REVNO)
-    PAGENAME: page name (unicode)
-    ATTACHMENTNAME: attachment name (unicode) or None (for pages)
-    REVNO: revision number (int) - meaning "look at that revision",
-           or None - meaning "look at all revisions"
+    Each job is a tuple like: (PAGENAME, ATTACHMENTNAME, REVNO)::
+
+        PAGENAME: page name (unicode)
+        ATTACHMENTNAME: attachment name (unicode) or None (for pages)
+        REVNO: revision number (int) - meaning "look at that revision",
+               or None - meaning "look at all revisions"
     """
 
     def __init__(self, request, xapian_dir, queuename, timeout=10.0):
--- a/MoinMoin/security/__init__.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/security/__init__.py	Tue Mar 01 17:34:56 2011 +0100
@@ -35,16 +35,16 @@
 
     When sub classing this class, you must extend the class methods, not
     replace them, or you might break the ACLs in the wiki.
-    Correct sub classing looks like this:
+    Correct sub classing looks like this::
 
-    def read(self, itemname):
-        # Your special security rule
-        if something:
-            return False
+        def read(self, itemname):
+            # Your special security rule
+            if something:
+                return False
 
-        # Do not just return True or you break (ignore) ACLs!
-        # This call will return correct permissions by checking ACLs:
-        return Permissions.read(itemname)
+            # Do not just return True or you break (ignore) ACLs!
+            # This call will return correct permissions by checking ACLs:
+            return Permissions.read(itemname)
     """
 
     def __init__(self, user):
@@ -291,7 +291,8 @@
     Parse acl string and return the next entry on each call to next.
     Implements the Iterator protocol.
 
-    Usage:
+    Usage::
+
         iter = ACLStringIterator(cfg.acl_rights_valid, 'user name:right')
         for modifier, entries, rights in iter:
             # process data
--- a/MoinMoin/security/textcha.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/security/textcha.py	Tue Mar 01 17:34:56 2011 +0100
@@ -13,8 +13,9 @@
     could adapt to that).
 
     TODO:
-    * roundtrip the question in some other way:
-     * make sure a q/a pair in the POST is for the q in the GET before
+
+    * roundtrip the question in some other way, make sure a q/a pair in
+      the POST is for the q in the GET before
     * make some nice CSS
     * make similar changes to GUI editor
 """
@@ -130,15 +131,16 @@
         """ check if textchas are enabled.
 
             They can be disabled for all languages if you use textchas = None or = {},
-            also they can be disabled for some specific language, like:
-            textchas = {
-                'en': {
-                    'some question': 'some answer',
+            also they can be disabled for some specific language, like::
+
+                textchas = {
+                    'en': {
+                        'some question': 'some answer',
+                        # ...
+                    },
+                    'de': {}, # having no questions for 'de' means disabling textchas for 'de'
                     # ...
-                },
-                'de': {}, # having no questions for 'de' means disabling textchas for 'de'
-                # ...
-            }
+                }
         """
         return not not self.textchas # we don't want to return the dict
 
--- a/MoinMoin/storage/backends/fs19_logfile.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/storage/backends/fs19_logfile.py	Tue Mar 01 17:34:56 2011 +0100
@@ -24,10 +24,11 @@
 class LineBuffer:
     """
     Reads lines from a file
-        self.len      number of lines in self.lines
-        self.lines    list of lines (unicode)
-        self.offsets  list of file offsets for each line. additionally the position
-                      after the last read line is stored into self.offsets[-1]
+
+    :ivar len: number of lines in self.lines
+    :ivar lines: list of lines (unicode)
+    :ivar offsets: list of file offsets for each line. additionally the position
+                   after the last read line is stored into self.offsets[-1]
     """
     def __init__(self, file, offset, size, forward=True):
         """
@@ -84,6 +85,7 @@
     """
     .filter: function that gets the values from .parser.
              must return True to keep it or False to remove it
+
     Overwrite .parser() and .add() to customize this class to special log files
     """
 
@@ -418,11 +420,12 @@
 
     def parser(self, line):
         """
+        Converts the line from file to program representation.
+        This implementation uses TAB separated strings.
+        This method should be overwritten by the sub classes.
+
         :param line: line as read from file
         :returns: parsed line or None on error
-        Converts the line from file to program representation
-        This implementation uses TAB separated strings.
-        This method should be overwritten by the sub classes.
         """
         return line.split("\t")
 
--- a/MoinMoin/storage/backends/hg.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/storage/backends/hg.py	Tue Mar 01 17:34:56 2011 +0100
@@ -7,6 +7,7 @@
     This package contains code for MoinMoin storage backend using a
     Mercurial (hg) distributed version control system. This backend provides
     several advantages compared to MoinMoin's default filesystem backend:
+
     - revisioning and concurrency issues handled using Mercurial's internal
       mechanisms
     - cloning of the page database, allowing easy backup, synchronization and
--- a/MoinMoin/storage/backends/indexing.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/storage/backends/indexing.py	Tue Mar 01 17:34:56 2011 +0100
@@ -326,6 +326,7 @@
         remove a revision <revno> of item <uuid>
 
         Note:
+
         * does not update metadata values cached in item (this is only a
           problem if you delete latest revision AND you don't delete the
           whole item anyway)
--- a/MoinMoin/storage/backends/sqla.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/storage/backends/sqla.py	Tue Mar 01 17:34:56 2011 +0100
@@ -46,6 +46,7 @@
     ====
     The following is a list of things that need to be done before this backend can be used productively
     (not including beta tests):
+
         * Data.read must be changed to operate on dynamically loaded chunks. I.e., the data._chunks must
           be set to lazy='dynamic', which will then be a query instead of a collection.
         * Find a proper solution for methods that issue many SQL queries. Especially search_items is
--- a/MoinMoin/util/lock.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/util/lock.py	Tue Mar 01 17:34:56 2011 +0100
@@ -317,8 +317,10 @@
     at all in that case.
 
     Of course this doesn't work for us on the win32 platform:
+
     * using MoveFileEx requires opening the file with some FILE_SHARE_DELETE
       mode - we currently don't do that
+
     We currently solve by using the non-lazy locking code in ReadLock class.
     """
     def __init__(self, dir, timeout=None):
--- a/MoinMoin/util/paramparser.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/util/paramparser.py	Tue Mar 01 17:34:56 2011 +0100
@@ -66,12 +66,16 @@
     them out afterwards.
 
     The function can also do bracketing, i.e. parse expressions
-    that contain things like
+    that contain things like::
+
         "(a (a b))" to ['(', 'a', ['(', 'a', 'b']],
+
     in this case, as in this example, the returned list will
     contain sub-lists and the brackets parameter must be a list
-    of opening and closing brackets, e.g.
+    of opening and closing brackets, e.g.::
+
         brackets = ['()', '<>']
+
     Each sub-list's first item is the opening bracket used for
     grouping.
     Nesting will be observed between the different types of
@@ -83,7 +87,8 @@
 
     If multikey is True (along with setting name_value_separator),
     then the returned tuples for (key, value) pairs can also have
-    multiple keys, e.g.
+    multiple keys, e.g.::
+
         "a=b=c" -> ('a', 'b', 'c')
 
     :param args: arguments to parse
--- a/MoinMoin/wikiutil.py	Mon Feb 28 22:42:52 2011 +0100
+++ b/MoinMoin/wikiutil.py	Tue Mar 01 17:34:56 2011 +0100
@@ -348,7 +348,7 @@
     def sanitize(self):
         """ convert to some representation that makes sense - this is not necessarily
             conformant to /etc/mime.types or IANA listing, but if something is
-            readable text, we will return some text/* mimetype, not application/*,
+            readable text, we will return some ``text/*`` mimetype, not ``application/*``,
             because we need text/plain as fallback and not application/octet-stream.
         """
         self.major, self.minor = MIMETYPES_sanitize_mapping.get((self.major, self.minor), (self.major, self.minor))
@@ -401,8 +401,9 @@
             module is not found) - e.g. first "text_python", next "text".
             Finally, we yield "application_octet_stream" as the most general
             mimetype we have.
+
             Hint: the fallback handler module for text/* should be implemented
-                  in module "text" (not "text_plain")
+            in module "text" (not "text_plain")
         """
         mimetype = self.mime_type()
         modname = mimetype.replace("/", "_").replace("-", "_").replace(".", "_")
@@ -510,13 +511,14 @@
     return "/!\\ '''Edit conflict" in text
 
 def anchor_name_from_text(text):
-    '''
+    """
     Generate an anchor name from the given text.
     This function generates valid HTML IDs matching: [A-Za-z][A-Za-z0-9:_.-]*
+
     Note: this transformation has a special feature: when you feed it with a
-          valid ID/name, it will return it without modification (identity
-          transformation).
-    '''
+    valid ID/name, it will return it without modification (identity
+    transformation).
+    """
     quoted = werkzeug.url_quote_plus(text, charset='utf-7', safe=':')
     res = quoted.replace('%', '.').replace('+', '_')
     if not res[:1].isalpha():
@@ -607,10 +609,11 @@
     Calculate a cache key (ascii only)
 
     Important key properties:
-    * The key must be different for different **kw.
+
+    * The key must be different for different <kw>.
     * Key is pure ascii
 
-    :param **kw: keys/values to compute cache key from
+    :param kw: keys/values to compute cache key from
     """
     return hashlib.md5(repr(kw)).hexdigest()