Commits

Roger Haase committed 92a9c6e

reduce number of warning and error messages when running "m docs"

Comments (0)

Files changed (19)

MoinMoin/converter/docbook_in.py

 
     def visit_docbook_admonition(self, element, depth):
         """
-        <tag.name> --> <admonition tye='tag.name'>
+        <tag.name> --> <admonition type='tag.name'>
         """
         attrib = {}
         key = moin_page('type')
 
     def visit_qandaentry_number(self, element, depth):
         """
-        <question>Q</question><answer>A</answer>
-          --> <list-item>
+        Convert::
+
+            <question>Q</question><answer>A</answer>
+
+        to::
+
+            <list-item>
                 <list-item-body><p>Q</p><p>A</p></list-item-body>
-              </list-item>
+            </list-item>
         """
         items = []
         for child in element:
 
     def visit_qandaentry_qanda(self, element, depth):
         """
-        <question>Q body</question><answer>A Body</answer>
-        --> <list-item>
-              <list-item-label>Q:</list-item-label>
-              <list-item-body>Q Body</list-item-body>
+        Convert::
+
+            <question>Q body</question><answer>A Body</answer>
+
+        to::
+
+            <list-item>
+                <list-item-label>Q:</list-item-label>
+                <list-item-body>Q Body</list-item-body>
             </list-item>
             <list-item>
-              <list-item-label>A:</list-item-label>
-              <list-item-body>A Body</list-item-body>
+                <list-item-label>A:</list-item-label>
+                <list-item-body>A Body</list-item-body>
             </list-item>
         """
         items = []

MoinMoin/converter/docbook_out.py

 
     def visit_moinpage_blockquote(self, element):
         """
-        <blockquote>text<blockquote>
-          --> <blockquote>
-                <attribution>Uknown</attribution>
+        Convert::
+
+            <blockquote>text<blockquote>
+
+        to::
+
+            <blockquote>
+                <attribution>Unknown</attribution>
                 <simpara>text</text>
-              </blockquote>
+            </blockquote>
+
+        Expand::
 
         <blockquote source="author">text</blockquote>
-          --> <blockquote>
-                <attribution>Uknown</attribution>
+
+        output::
+
+            <blockquote>
+                <attribution>author</attribution>
                 <simpara>text</text>
-              </blockquote>
+            </blockquote>
         """
         author = element.get(moin_page('source'))
         if not author:
 
     def visit_moinpage_object(self, element):
         """
+        Convert::
+
         <object type='image/' xlink:href='uri'/>
-        --> <inlinemediaobject>
-              <imageobject>
-                <imagedata fileref="uri" />
-              </imageobject>
+
+        to::
+
+            <inlinemediaobject>
+                  <imageobject>
+                        <imagedata fileref="uri" />
+                  </imageobject>
             </inlinemediaobject>
 
         Similar for video and audio object.

MoinMoin/converter/html_in.py

 
     def visit_xhtml_list(self, element):
         """
-        Convert a list of item (whatever the type : ordered or unordered)
-        So we have a html code like :
-        <ul>
-            <li>Item 1</li>
-            <li>Item 2</li>
-        </ul>
+        Convert a list of items (whatever the type : ordered or unordered)
+        So we have html code like::
 
-        Which will be convert like :
-        <list>
-            <list-item>
-                <list-item-body>Item 1</list-item-body>
-            </list-item>
-            <list-item>
-                <list-item-body>Item 2</list-item-body>
-            </list-item>
-        </list>
+            <ul>
+                <li>Item 1</li>
+                <li>Item 2</li>
+            </ul>
+
+        Which will be converted to::
+
+            <list>
+                <list-item>
+                    <list-item-body>Item 1</list-item-body>
+                </list-item>
+                <list-item>
+                    <list-item-body>Item 2</list-item-body>
+                </list-item>
+            </list>
         """
         # We will define the appropriate attribute
         # according to the type of the list
 
     def visit_xhtml_dl(self, element):
         """
-        Convert a list of definition. The conversion is like :
-        <dl>
-            <dt>Label 1</dt><dd>Text 1</dd>
-            <dt>Label 2</dt><dd>Text 2</dd>
-        </dl>
+        Convert a list of definition. The starting structure::
 
-        will give
+            <dl>
+                <dt>Label 1</dt><dd>Text 1</dd>
+                <dt>Label 2</dt><dd>Text 2</dd>
+            </dl>
 
-        <list>
-            <list-item>
-                <list-item-label>Label 1</list-item-label>
-                <list-item-body>Text 1</list-item-body>
-            </list-item>
-            <list-item>
-                <list-item-label>Label 2</list-item-label>
-                <list-item-body>Text 2</list-item-body>
-            </list-item>
-        </list>
+        will be converted to::
+
+            <list>
+                <list-item>
+                    <list-item-label>Label 1</list-item-label>
+                    <list-item-body>Text 1</list-item-body>
+                </list-item>
+                <list-item>
+                    <list-item-label>Label 2</list-item-label>
+                    <list-item-body>Text 2</list-item-body>
+                </list-item>
+            </list>
         """
         list_item = []
         pair = []
 
     def visit_xhtml_li(self, element):
         """
-        NB : A list item (<li>) is like the following snippet :
-        <list-item>
-            <list-item-label>label</list-item-label>
-            <list-item-body>Body</list-item-body>
-        </list-item>
+        NB : A list item (<li>) is like the following snippet::
+
+            <list-item>
+                <list-item-label>label</list-item-label>
+                <list-item-body>Body</list-item-body>
+            </list-item>
 
         For <li> element, there is no label
         """

MoinMoin/converter/html_out.py

 
     def eval_object_type(self, mimetype, href):
         """
-        Returns the type of an object.
-        Return value is an str, one of the following:
-            image, video, audio, object
+        Returns the type of an object as a str, one of the following: img, video, audio, object
         """
         if Type('image/').issupertype(mimetype):
             return "img"

MoinMoin/converter/include.py

 After expanding the include elements, in many cases it is necessary to adjust
 the DOM to prevent the generation of invalid HTML.  Using a simple example,
 "\n{{SomeItem}}\n", the starting DOM structure created by the moinwiki_in.py
-(or other parser) is:
+(or other parser) is::
 
     Page > Body > P > Include
 
-After expansion of the Include, the structure will be:
+After expansion of the Include, the structure will be::
 
     Page > Body > P > Page > Body > (P | Div | Object |...)
 
 almost any type of element is valid within a table cell's td.
 
 But without DOM adjustment, "\n{{Block}}\n" will generate invalid HTML
-because html_out.py will convert the DOM structure:
+because html_out.py will convert the DOM structure::
 
     Page > Body > P > Page > Body > (Pre | Div | P, P... | ...)
 
-into:
+into::
 
     ...<body><p><div>...</div></p></body>...
 
 
 In some cases it is desirable to coerce a transcluded small image or phrase into a
 inline element embedded within a paragraph. Here html_out.py will wrap the transclusion in
-a Span rather than a Div or convert a P-tag containing a phrase into a Span.
+a Span rather than a Div or convert a P-tag containing a phrase into a Span::
 
     "My pet {{bird.jpg}} flys.", "[[SomePage|{{Logo.png}}]]" or "Yes, we have {{no}} bananas."
 
 In complex cases where a block level item is transcluded within the midst of
-several levels of text markup, such as:
+several levels of text markup, such as::
 
-   "\nplain ''italic '''bold {{BlockItem}} bold''' italic'' plain\n"
+   "plain ''italic '''bold {{BlockItem}} bold''' italic'' plain"
 
-then we must avoid generating invalid html like:
+then we must avoid generating invalid html like::
 
     <p>plain <emphasis>italic <strong>bold <div>
     ...</div> bold</strong> italic</emphasis> plain</p>
 
-where <div...</div> contains the transcluded item, but rather:
+where <div>...</div> contains the transcluded item, but rather::
 
     <p>plain <emphasis>italic <strong>bold</strong></emphasis></p><div>
     ...</div><p><emphasis><strong> bold</strong> italic</emphasis> plain</p>
 
 When a block element is embedded within a comment, it is important that the
 class="comment" is copied to the transclusion to provide the show/hide and
-highlighted styles normally applied to comments.
+highlighted styles normally applied to comments::
 
-    "\n/* normal ''italic ~-small {{detail.csv}} small-~ italic'' normal */\n".
+    /* normal ''italic ~-small {{detail.csv}} small-~ italic'' normal */
 
 Conveniently, the class="comment" is added to the span element within the
 moinwiki_in.py parser and is available to include.py.  However, the moin-big

MoinMoin/converter/markdown_in.py

     """
     Removes HTML or XML character references and entities from a text string.
 
-    @param text The HTML (or XML) source text.
-    @return The plain text, as a Unicode string, if necessary.
+    :param text: The HTML (or XML) source text.
+    :returns: The plain text, as a Unicode string, if necessary.
     """
 
     # http://effbot.org/zone/re-sub.htm#unescape-html
 
     def visit_li(self, element):
         """
-        NB : A list item (<li>) is like the following snippet :
-        <list-item>
-            <list-item-label>label</list-item-label>
-            <list-item-body>Body</list-item-body>
-        </list-item>
+        NB : A list item (<li>) is like the following snippet::
+
+            <list-item>
+                <list-item-label>label</list-item-label>
+                <list-item-body>Body</list-item-body>
+            </list-item>
 
         For <li> element, there is no label
         """
     def visit_list(self, element):
         """
         Convert a list of item (whatever the type : ordered or unordered)
-        So we have a html code like :
-        <ul>
-            <li>Item 1</li>
-            <li>Item 2</li>
-        </ul>
+        So we have html code like::
 
-        Which will be convert like :
-        <list>
-            <list-item>
-                <list-item-body>Item 1</list-item-body>
-            </list-item>
-            <list-item>
-                <list-item-body>Item 2</list-item-body>
-            </list-item>
-        </list>
+            <ul>
+                <li>Item 1</li>
+                <li>Item 2</li>
+            </ul>
+
+        Which will be converted to::
+
+            <list>
+                <list-item>
+                    <list-item-body>Item 1</list-item-body>
+                </list-item>
+                <list-item>
+                    <list-item-body>Item 2</list-item-body>
+                </list-item>
+            </list>
         """
         # We will define the appropriate attribute
         # according to the type of the list

MoinMoin/converter/mediawiki_in.py

         """
         Parses media wiki arguments, this is taken from _args_wiki > parse function. The primary difference
         being that mediawiki breaks on pipes whereas the default parser breaks on spaces. Apart from that
-        this parser also supports a few extra characters such as "<, >, ., /", mostly for URL linking
+        this parser also supports a few extra characters such as "<, >, ., /", mostly for URL linking.
 
         :param input: can be like a|b|c=f|something else caption|g='long caption'|link=http://google.com
-        :return Arguments instance
+        :returns: Arguments instance
         """
         parse_rules = r'''
         (?:

MoinMoin/items/content.py

 
 class Draw(TarMixin, Image):
     """
-    Base class for *Draw that use special Java/Javascript applets to modify and store data in a tar file.
+    Base class for drawing apps that use special Java/Javascript applets to modify and store data in a tar file.
     """
     group = GROUP_DRAWING
 
     def __init__(self, toaddrs=[], subject=u''):
         """ Initialize the handler
 
-        @param toaddrs: address or a list of email addresses whom to send email
-        @param subject: unicode email's subject
+        :param toaddrs: address or a list of email addresses whom to send email
+        :param subject: unicode email's subject
         """
         logging.Handler.__init__(self)
         if isinstance(toaddrs, basestring):

MoinMoin/script/win/wget.py

 import urllib
 
 
-if len(sys.argv) == 3:
-    urllib.urlretrieve(sys.argv[1], sys.argv[2])
-else:
-    print "Error: incorrect parameters passed."
-    print "Usage:  python <path_to>wget.py <url> <output_file>"
+if __name__ == '__main__':
+    if len(sys.argv) == 3:
+        urllib.urlretrieve(sys.argv[1], sys.argv[2])
+    else:
+        print "Error: incorrect parameters passed."
+        print "Usage:  python <path_to>wget.py <url> <output_file>"

MoinMoin/security/__init__.py

 
     Correct subclassing looks like this::
 
-    class MySecPol(DefaultSecurityPolicy):
-        def read(self, itemname):
-            # Your special security rule
-            if something:
-                return False
+        class MySecPol(DefaultSecurityPolicy):
+            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 super(MySecPol, self).read(itemname)
+                # Do not just return True or you break (ignore) ACLs!
+                # This call will return correct permissions by checking ACLs:
+                return super(MySecPol, self).read(itemname)
     """
     def __init__(self, user):
         self.names = user.name

MoinMoin/storage/middleware/indexing.py

         """
         Return item identified by the query (may be a new or existing item).
 
-        :kwargs **query: e.g. name_exact=u"Foo" or itemid="..." or ...
-                         (must be a unique fieldname=value for the latest-revs index)
+        :kwargs query: e.g. name_exact=u"Foo" or itemid="..." or ...
+                     (must be a unique fieldname=value for the latest-revs index)
         """
         return Item(self, **query)
 
         """
         Return item identified by the query (must be a new item).
 
-        :kwargs **query: e.g. name_exact=u"Foo" or itemid="..." or ...
-                         (must be a unique fieldname=value for the latest-revs index)
+        :kwargs query: e.g. name_exact=u"Foo" or itemid="..." or ...
+                     (must be a unique fieldname=value for the latest-revs index)
         """
         return Item.create(self, **query)
 
         """
         Return item identified by query (must be an existing item).
 
-        :kwargs **query: e.g. name_exact=u"Foo" or itemid="..." or ...
-                         (must be a unique fieldname=value for the latest-revs index)
+        :kwargs query: e.g. name_exact=u"Foo" or itemid="..." or ...
+                     (must be a unique fieldname=value for the latest-revs index)
         """
         return Item.existing(self, **query)
 

MoinMoin/storage/middleware/protecting.py

         for a fully-qualified itemname (namespace:name), get the acl configuration
         for that (part of the) namespace.
 
-        @param fqname: fully qualified itemname
-        @returns: acl configuration (acl dict from the acl_mapping)
+        :param fqname: fully qualified itemname
+        :returns: acl configuration (acl dict from the acl_mapping)
         """
         itemname = fqname.value if fqname.field == NAME_EXACT else u''
         for prefix, acls in self.acl_mapping:

MoinMoin/storage/middleware/serialization.py

 """
 MoinMoin - backend serialization / deserialization
 
-We use a simple custom format here:
+We use a simple custom format here::
 
-4 bytes length of meta (m)
-m bytes metadata (json serialization, utf-8 encoded)
-        (the metadata contains the data length d in meta[SIZE])
-d bytes binary data
-... (repeat for all meta/data)
-4 bytes 00 (== length of next meta -> there is none, this is the end)
+    4 bytes length of meta (m)
+    m bytes metadata (json serialization, utf-8 encoded)
+            (the metadata contains the data length d in meta[SIZE])
+    d bytes binary data
+    ... (repeat for all meta/data)
+    4 bytes 00 (== length of next meta -> there is none, this is the end)
 """
 
 

MoinMoin/themes/__init__.py

     the field is a UUID or not.
 
     :param fqname: fqname, namedtuple
-    :param length maximum length for shortened fqnames in case the field
-    is not a UUID.
+    :param length: maximum length for shortened fqnames in case the field is not a UUID.
     :rtype: unicode
     :returns: shortened fqname.
     """
         """ Subscribe to a wiki page.
 
         The user can subscribe in 5 different ways:
+
         * by itemid - ITEMID:<itemid value>
         * by item name - NAME:<namespace>:<name value>
         * by a tagname - TAGS:<namespace>:<tag value>
         * by a prefix name - NAMEPREFIX:<namespace>:<name prefix>
         * by a regular expression - NAMERE:<namespace>:<name regexp>
 
-:       :param keyword: the keyword (itemid, name, tags, nameprefix, namere) by which
+        :param keyword: the keyword (itemid, name, tags, nameprefix, namere) by which
                         the type of the subscription is determined
         :param value: the subscription value (itemid, name, tag, regexp or nameprefix value)
         :param namespace: the namespace of the subscription; itemid keyword doesn't
-                            require a namespace
+                        require a namespace
         :rtype: bool
         :returns: if user was subscribed
         """
         """ Check if the session token is valid.
 
         Invalid session tokens happen for these cases:
+
         a) there are multiple sessions (different machines, different browsers)
            open for same user. the user then changes the password in one of
            these, which creates a new session key in the profile also, which

MoinMoin/util/__init__.py

 
 
 def getPageContent(results, offset, results_per_page):
-    """ Selects the content to show on a single page
-        :param results: the whole result, from which results for one page will be selected (generally a generator
-               but could be a list also),
-        :param offset: after skipping how many results, the selection of results for that page will be done (int),
-        :param results_per_page: number of results to be shown on a single page (int)
+    """
+    Selects the content to show on a single page
 
-        :rtype: tuple
-        :returns: selected_result (list),
-                  offset for next page (If 0 then no next page),
-                  offset for previous page (If less than 0, then no previous page)
+    :param results: the whole result, from which results for one page will be selected (generally a generator
+           but could be a list also),
+    :param offset: after skipping how many results, the selection of results for that page will be done (int),
+    :param results_per_page: number of results to be shown on a single page (int)
+
+    :rtype: tuple
+    :returns: selected_result (list),
+              offset for next page (If 0 then no next page),
+              offset for previous page (If less than 0, then no previous page)
     """
     count = 0
     maxcount = offset + results_per_page

MoinMoin/util/interwiki.py

     """
     Split a fully qualified url into namespace, field and pagename
     url -> [NAMESPACE/][@FIELD/]NAME
-    param: url: the url to split
-    returns: a namedtuple CompositeName(namespace, field, itemname)
-    Example:
+
+    :param url: the url to split
+    :returns: a namedtuple CompositeName(namespace, field, itemname)
+    Examples::
+
         url: u'ns1/ns2/@itemid/Page' return u'ns1/ns2', u'itemid', u'Page'
         url: u'@revid/OtherPage' return u'', u'revid', u'OtherPage'
         url: u'ns1/Page' return u'ns1', u'', u'Page'
 
 
 def split_interwiki(wikiurl):
-    """ Split a interwiki name, into wikiname and pagename, e.g:
+    """
+    Split a interwiki name, into wikiname and pagename, e.g::
 
-    'MoinMoin/FrontPage' -> "MoinMoin", "", "", "FrontPage"
-    'FrontPage' -> "Self", "", "", "FrontPage"
-    'MoinMoin/Page with blanks' -> "MoinMoin", "", "", "Page with blanks"
-    'MoinMoin/' -> "MoinMoin", "", "", ""
-    'MoinMoin/@Someid/SomeValue' -> "MoinMoin", "", "Someid", "SomeValue" if Someid field exists or "MoinMoin", "", "", "Someid/SomePage" if not
-    'MoinMoin/interwikins/AnyPage' -> "MoinMoin", "interwikins", "", "AnyPage"
-    'ns/AnyPage' -> "Self", "ns", "", "AnyPage" if ns namespace exists or "Self", "", "", "ns:AnyPage" if not.
-    'ns1/ns2/AnyPage' -> "Self", "ns1/ns2", "", "AnyPage" if ns1/ns2 namespace exists OR
-                         "Self", "ns1", "", "ns2/AnyPage" if ns1 namespace exists OR
-                         "Self", "", "", "ns1/ns2/AnyPage" else.
-    'MoinMoin/ns/@Somefield/AnyPage' -> "MoinMoin", "ns", "", "@Somefield/AnyPage" if ns namespace exists and field Somefield does not OR
-                                     "MoinMoin", "ns", "Somefield", "AnyPage" if ns namespace and field Somefield exist OR
-                                     "MoinMoin", "", "", "ns/@Somefield/AnyPage" else.
-    :param wikiurl: the url to split
-    :rtype: tuple
-    :returns: (wikiname, namespace, field, pagename)
+        'MoinMoin/FrontPage' -> "MoinMoin", "", "", "FrontPage"
+        'FrontPage' -> "Self", "", "", "FrontPage"
+        'MoinMoin/Page with blanks' -> "MoinMoin", "", "", "Page with blanks"
+        'MoinMoin/' -> "MoinMoin", "", "", ""
+        'MoinMoin/@Someid/SomeValue' -> "MoinMoin", "", "Someid", "SomeValue" if Someid field exists or "MoinMoin", "", "", "Someid/SomePage" if not
+        'MoinMoin/interwikins/AnyPage' -> "MoinMoin", "interwikins", "", "AnyPage"
+        'ns/AnyPage' -> "Self", "ns", "", "AnyPage" if ns namespace exists or "Self", "", "", "ns:AnyPage" if not.
+        'ns1/ns2/AnyPage' -> "Self", "ns1/ns2", "", "AnyPage" if ns1/ns2 namespace exists OR
+                             "Self", "ns1", "", "ns2/AnyPage" if ns1 namespace exists OR
+                             "Self", "", "", "ns1/ns2/AnyPage" else.
+        'MoinMoin/ns/@Somefield/AnyPage' -> "MoinMoin", "ns", "", "@Somefield/AnyPage" if ns namespace exists and field Somefield does not OR
+                                         "MoinMoin", "ns", "Somefield", "AnyPage" if ns namespace and field Somefield exist OR
+                                         "MoinMoin", "", "", "ns/@Somefield/AnyPage" else.
+        :param wikiurl: the url to split
+        :rtype: tuple
+        :returns: (wikiname, namespace, field, pagename)
     """
     if not isinstance(wikiurl, unicode):
         wikiurl = wikiurl.decode('utf-8')

MoinMoin/util/iri.py

 
     def __init__(self, _iri=None, _quoted=True, scheme=None, authority=None, path=None, query=None, fragment=None):
         """
-        @param _iri A full IRI in unicode
-        @param scheme Scheme part of the IRI, overrides the same part of the IRI.
-        @param authority Authority part of the IRI, overrides the same part of the IRI.
-        @param path Path part of the IRI, overrides the same part of the IRI.
-        @param query Query part of the IRI, overrides the same part of the IRI.
-        @param fragment Fragment part of the IRI, overrides the same part of the IRI.
+        :param _iri: A full IRI in unicode
+        :param scheme: Scheme part of the IRI, overrides the same part of the IRI.
+        :param authority: Authority part of the IRI, overrides the same part of the IRI.
+        :param path: Path part of the IRI, overrides the same part of the IRI.
+        :param query: Query part of the IRI, overrides the same part of the IRI.
+        :param fragment: Fragment part of the IRI, overrides the same part of the IRI.
         """
 
         if isinstance(_iri, Iri):