Document compat, nodes.extras, Attribute, Parameter

mwparserfromhell/__init__.py

@@ -37,3 +37,4 @@ __email__ = "ben.kurtovic@verizon.net"
 from . import nodes, parser, smart_list, string_mixin, wikicode
 
 parse = lambda text: parser.Parser(text).parse()
+parse.__doc__ = """Short for mwparserfromhell.parser.Parser(text).parse()."""

mwparserfromhell/compat.py

@@ -1,7 +1,11 @@
 # -*- coding: utf-8 -*-
 
 """
-Implements support for both Python 2 and Python 3.
+Implements support for both Python 2 and Python 3 by defining common types in
+terms of their Python 2/3 variants. For example, :py:class:`str` is set to
+:py:class:`unicode` on Python 2 but :py:class:`str` on Python 3; likewise,
+:py;class:`bytes` is :py:class:`str` on 2 but :py:class:`bytes` on 3. These
+types are meant to be imported directly from within the parser's modules.
 """
 
 import sys

mwparserfromhell/nodes/extras/__init__.py

@@ -20,5 +20,11 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+"""
+This package contains objects used by
+:py:class:`~mwparserfromhell.nodes.Node`\ s, but are not nodes themselves.
+This includes the parameters of Templates or the attributes of HTML tags.
+"""
+
 from .attribute import Attribute
 from .parameter import Parameter

mwparserfromhell/nodes/extras/attribute.py

@@ -28,6 +28,13 @@ from ...string_mixin import StringMixIn
 __all__ = ["Attribute"]
 
 class Attribute(StringMixIn):
+    """Represents an attribute of an HTML tag.
+
+    This is used by :py:class:`~mwparserfromhell.nodes.tag.Tag` objects. For
+    example, the tag ``<ref name="foo">`` contains an Attribute whose name is
+    ``"name"`` and whose value is ``"foo"``.
+    """
+
     def __init__(self, name, value=None, quoted=True):
         super(Attribute, self).__init__()
         self._name = name
@@ -43,12 +50,15 @@ class Attribute(StringMixIn):
 
     @property
     def name(self):
+        """The name of the attribute as a ``Wikicode`` object."""
         return self._name
 
     @property
     def value(self):
+        """The value of the attribute as a ``Wikicode`` object."""
         return self._value
 
     @property
     def quoted(self):
+        """Whether the attribute's value is quoted with double quotes."""
         return self._quoted

mwparserfromhell/nodes/extras/parameter.py

@@ -29,6 +29,14 @@ from ...utils import parse_anything
 __all__ = ["Parameter"]
 
 class Parameter(StringMixIn):
+    """Represents a paramater of a template.
+
+    For example, the template ``{{foo|bar|spam=eggs}}`` contains two
+    Parameters: one whose name is ``"1"``, value is ``"bar"``, and ``showkey``
+    is ``False``, and one whose name is ``"spam"``, value is ``"eggs"``, and
+    ``showkey`` is ``True``.
+    """
+
     def __init__(self, name, value, showkey=True):
         super(Parameter, self).__init__()
         self._name = name
@@ -42,14 +50,17 @@ class Parameter(StringMixIn):
 
     @property
     def name(self):
+        """The name of the parameter as a ``Wikicode`` object."""
         return self._name
 
     @property
     def value(self):
+        """The value of the parameter as a ``Wikicode`` object."""
         return self._value
 
     @property
     def showkey(self):
+        """Whether to show the parameter's key (i.e., its "name")."""
         return self._showkey
 
     @name.setter

mwparserfromhell/smart_list.py

@@ -68,6 +68,7 @@ class SmartList(list):
         >>> parent
         [0, 1, 2, 3, 4]
     """
+
     def __init__(self, iterable=None):
         if iterable:
             super(SmartList, self).__init__(iterable)
@@ -187,6 +188,7 @@ class _ListProxy(list):
     instead, whenever the list is needed, it builds it dynamically using the
     :py:meth:`_render` method.
     """
+
     def __init__(self, parent, sliceinfo):
         super(_ListProxy, self).__init__()
         self._parent = parent

mwparserfromhell/string_mixin.py

@@ -52,6 +52,7 @@ class StringMixIn(object):
     :py:meth:`__unicode__` instead of the immutable ``self`` like the regular
     ``str`` type.
     """
+
     if py3k:
         def __str__(self):
             return self.__unicode__()