Simplify docs massively.

docs/api/mwparserfromhell.nodes.rst

@@ -7,6 +7,7 @@ nodes Package
 .. automodule:: mwparserfromhell.nodes
 
 .. autoclass:: mwparserfromhell.nodes.Node
+    :special-members:
 
 :mod:`heading` Module
 ---------------------

mwparserfromhell/__init__.py

@@ -37,4 +37,4 @@
 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()``."
+parse.__doc__ = "Short for :py:meth:`.Parser.parse`."

mwparserfromhell/nodes/__init__.py

@@ -21,14 +21,12 @@
 # SOFTWARE.
 
 """
-This package contains :py:class:`~mwparserfromhell.wikicode.Wikicode` "nodes",
-which represent a single unit of wikitext, such as a Template, an HTML tag,
-a Heading, or plain text. The node "tree" is far from flat, as most types can
-contain additional :py:class:`~mwparserfromhell.wikicode.Wikicode` types within
-them - and with that, more nodes. For example, the name of a
-:py:class:`~mwparserfromhell.nodes.template.Template` is a
-:py:class:`~mwparserfromhell.wikicode.Wikicode` object that can contain text or
-more templates.
+This package contains :py:class:`~.Wikicode` "nodes", which represent a single
+unit of wikitext, such as a Template, an HTML tag, a Heading, or plain text.
+The node "tree" is far from flat, as most types can contain additional
+:py:class:`~.Wikicode` types within them - and with that, more nodes. For
+example, the name of a :py:class:`~.Template` is a :py:class:`~.Wikicode`
+object that can contain text or more templates.
 """
 
 from __future__ import unicode_literals
@@ -43,15 +41,15 @@ class Node(StringMixIn):
 
     :py:meth:`__unicode__` must be overridden. It should return a ``unicode``
     or (``str`` in py3k) representation of the node. If the node contains
-    :py:class:`~mwparserfromhell.wikicode.Wikicode` objects inside of it,
-    :py:meth:`__iternodes__` should be overridden to yield tuples of
-    (``wikicode``, ``node_in_wikicode``) for each node in each wikicode, as
-    well as the node itself (``None``, ``self``). If the node is printable,
-    :py:meth:`__strip__` should be overridden to return the printable version
-    of the node - it does not have to be a string, but something that can be
-    converted to a string with ``str()``. Finally, :py:meth:`__showtree__` can
-    be overridden to build a nice tree representation of the node, if desired,
-    for :py:meth:`~mwparserfromhell.wikicode.Wikicode.get_tree`.
+    :py:class:`~.Wikicode` objects inside of it, :py:meth:`__iternodes__`
+    should be overridden to yield tuples of (``wikicode``,
+    ``node_in_wikicode``) for each node in each wikicode, as well as the node
+    itself (``None``, ``self``). If the node is printable, :py:meth:`__strip__`
+    should be overridden to return the printable version of the node - it does
+    not have to be a string, but something that can be converted to a string
+    with ``str()``. Finally, :py:meth:`__showtree__` can be overridden to build
+    a nice tree representation of the node, if desired, for
+    :py:meth:`~.Wikicode.get_tree`.
     """
     def __unicode__(self):
         raise NotImplementedError()

mwparserfromhell/nodes/extras/__init__.py

@@ -22,8 +22,8 @@
 
 """
 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.
+:py:class:`~.Node`\ s, but are not nodes themselves. This includes the
+parameters of Templates or the attributes of HTML tags.
 """
 
 from .attribute import Attribute

mwparserfromhell/nodes/extras/attribute.py

@@ -30,9 +30,9 @@
 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"``.
+    This is used by :py:class:`~.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):
@@ -50,12 +50,12 @@ def __unicode__(self):
 
     @property
     def name(self):
-        """The name of the attribute as a ``Wikicode`` object."""
+        """The name of the attribute as a :py:class:`~.Wikicode` object."""
         return self._name
 
     @property
     def value(self):
-        """The value of the attribute as a ``Wikicode`` object."""
+        """The value of the attribute as a :py:class:`~.Wikicode` object."""
         return self._value
 
     @property

mwparserfromhell/nodes/extras/parameter.py

@@ -50,12 +50,12 @@ def __unicode__(self):
 
     @property
     def name(self):
-        """The name of the parameter as a ``Wikicode`` object."""
+        """The name of the parameter as a :py:class:`~.Wikicode` object."""
         return self._name
 
     @property
     def value(self):
-        """The value of the parameter as a ``Wikicode`` object."""
+        """The value of the parameter as a :py:class:`~.Wikicode` object."""
         return self._value
 
     @property

mwparserfromhell/nodes/heading.py

@@ -53,7 +53,7 @@ def __showtree__(self, write, get, mark):
 
     @property
     def title(self):
-        """The title of the heading itself, as a ``Wikicode`` object."""
+        """The title of the heading, as a :py:class:`~.Wikicode` object."""
         return self._title
 
     @property

mwparserfromhell/nodes/tag.py

@@ -172,20 +172,19 @@ def type(self):
 
     @property
     def tag(self):
-        """The tag itself, as a ``Wikicode`` object."""
+        """The tag itself, as a :py:class:`~.Wikicode` object."""
         return self._tag
 
     @property
     def contents(self):
-        """The contents of the tag, as a ``Wikicode`` object."""
+        """The contents of the tag, as a :py:class:`~.Wikicode` object."""
         return self._contents
 
     @property
     def attrs(self):
         """The list of attributes affecting the tag.
 
-        Each attribute is an instance of
-        :py:class:`~mwparserfromhell.nodes.extras.attribute.Attribute`.
+        Each attribute is an instance of :py:class:`~.Attribute`.
         """
         return self._attrs
 

mwparserfromhell/nodes/template.py

@@ -152,7 +152,7 @@ def _remove_without_field(self, param, i, force_no_field):
 
     @property
     def name(self):
-        """The name of the template, as a ``Wikicode`` object."""
+        """The name of the template, as a :py:class:`~.Wikicode` object."""
         return self._name
 
     @property
@@ -184,11 +184,10 @@ def get(self, name):
         """Get the parameter whose name is *name*.
 
         The returned object is a
-        :py:class:`~mwparserfromhell.nodes.extras.parameter.Parameter`
-        instance. Raises :py:exc:`ValueError` if no parameter has this name.
-        Since multiple parameters can have the same name, we'll return the last
-        match, since the last parameter is the only one read by the MediaWiki
-        parser.
+        :py:class:`~.Parameter` instance. Raises :py:exc:`ValueError` if no
+        parameter has this name. Since multiple parameters can have the same
+        name, we'll return the last match, since the last parameter is the only
+        one read by the MediaWiki parser.
         """
         name = name.strip() if isinstance(name, basestring) else str(name)
         for param in reversed(self.params):
@@ -200,14 +199,14 @@ def add(self, name, value, showkey=None, force_nonconformity=False):
         """Add a parameter to the template with a given *name* and *value*.
 
         *name* and *value* can be anything parasable by
-        :py:func:`mwparserfromhell.utils.parse_anything`; pipes (and equal
-        signs, if appropriate) are automatically escaped from *value* where
-        applicable. If *showkey* is given, this will determine whether or not
-        to show the parameter's name (e.g., ``{{foo|bar}}``'s parameter has a
-        name of ``"1"`` but it is hidden); otherwise, we'll make a safe and
-        intelligent guess. If *name* is already a parameter, we'll replace its
-        value while keeping the same spacing rules unless *force_nonconformity*
-        is ``True``. We will also try to guess the dominant spacing convention
+        :py:func:`.utils.parse_anything`; pipes (and equal signs, if
+        appropriate) are automatically escaped from *value* where applicable.
+        If *showkey* is given, this will determine whether or not to show the
+        parameter's name (e.g., ``{{foo|bar}}``'s parameter has a name of
+        ``"1"`` but it is hidden); otherwise, we'll make a safe and intelligent
+        guess. If *name* is already a parameter, we'll replace its value while
+        keeping the same spacing rules unless *force_nonconformity* is
+        ``True``. We will also try to guess the dominant spacing convention
         when adding a new parameter using :py:meth:`_get_spacing_conventions`
         unless *force_nonconformity* is ``True``.
         """

mwparserfromhell/parser/__init__.py

@@ -22,9 +22,8 @@
 
 """
 This package contains the actual wikicode parser, split up into two main
-modules: the :py:mod:`~mwparserfromhell.parser.tokenizer` and the
-:py:mod:`~mwparserfromhell.parser.builder`. This module joins them together
-under one interface.
+modules: the :py:mod:`~.tokenizer` and the :py:mod:`~.builder`. This module
+joins them together under one interface.
 """
 
 try:
@@ -40,12 +39,9 @@ class Parser(object):
     """Represents a parser for wikicode.
 
     Actual parsing is a two-step process: first, the text is split up into a
-    series of tokens by the
-    :py:class:`~mwparserfromhell.parser.tokenizer.Tokenizer`, and then the
-    tokens are converted into trees of
-    :py:class:`~mwparserfromhell.wikicode.Wikicode` objects and
-    :py:class:`~mwparserfromhell.nodes.Node`\ s by the
-    :py:class:`~mwparserfromhell.parser.builder.Builder`.
+    series of tokens by the :py:class:`~.Tokenizer`, and then the tokens are
+    converted into trees of :py:class:`~.Wikicode` objects and
+    :py:class:`~.Node`\ s by the :py:class:`~.Builder`.
     """
 
     def __init__(self, text):
@@ -54,7 +50,7 @@ def __init__(self, text):
         self._builder = Builder()
 
     def parse(self):
-        """Return a string as a parsed ``Wikicode`` object tree."""
+        """Return a string as a parsed :py:class:`~.Wikicode` object tree."""
         tokens = self._tokenizer.tokenize(self.text)
         code = self._builder.build(tokens)
         return code

mwparserfromhell/parser/builder.py

@@ -34,10 +34,9 @@
 class Builder(object):
     """Combines a sequence of tokens into a tree of ``Wikicode`` objects.
 
-    To use, pass a list of :py:class:`~mwparserfromhell.parser.tokens.Token`\ s
-    to the :py:meth:`build` method. The list will be exhausted as it is parsed
-    and a :py:class:`~mwparserfromhell.wikicode.Wikicode` object will be
-    returned.
+    To use, pass a list of :py:class:`~.Token`\ s to the :py:meth:`build`
+    method. The list will be exhausted as it is parsed and a
+    :py:class:`~.Wikicode` object will be returned.
     """
 
     def __init__(self):

mwparserfromhell/parser/tokenizer.py

@@ -92,7 +92,7 @@ def _fail_route(self):
         """Fail the current tokenization route.
 
         Discards the current stack/context/textbuffer and raises
-        :py:exc:`~mwparserfromhell.parser.tokenizer.BadRoute`.
+        :py:exc:`~.BadRoute`.
         """
         self._pop()
         raise BadRoute()

mwparserfromhell/parser/tokens.py

@@ -24,10 +24,8 @@
 This module contains the token definitions that are used as an intermediate
 parsing data type - they are stored in a flat list, with each token being
 identified by its type and optional attributes. The token list is generated in
-a syntactically valid form by the
-:py:class:`~mwparserfromhell.parser.tokenizer.Tokenizer`, and then converted
-into the :py:class`~mwparserfromhell.wikicode.Wikicode` tree by the
-:py:class:`~mwparserfromhell.parser.builder.Builder`.
+a syntactically valid form by the :py:class:`~.Tokenizer`, and then converted
+into the :py:class`~.Wikicode` tree by the :py:class:`~.Builder`.
 """
 
 from __future__ import unicode_literals

mwparserfromhell/smart_list.py

@@ -21,10 +21,9 @@
 # SOFTWARE.
 
 """
-This module contains the :py:class:`~mwparserfromhell.smart_list.SmartList`
-type, as well as its :py:class:`~mwparserfromhell.smart_list._ListProxy` child,
-which together implement a list whose sublists reflect changes made to the main
-list, and vice-versa.
+This module contains the :py:class:`~.SmartList` type, as well as its
+:py:class:`~._ListProxy` child, which together implement a list whose sublists
+reflect changes made to the main list, and vice-versa.
 """
 
 from __future__ import unicode_literals
@@ -36,9 +35,8 @@
 def inheritdoc(method):
     """Set __doc__ of *method* to __doc__ of *method* in its parent class.
 
-    Since this is used on
-    :py:class:`~mwparserfromhell.smart_list.SmartList`, the "parent class" used
-    is ``list``. This function can be used as a decorator.
+    Since this is used on :py:class:`~.SmartList`, the "parent class" used is
+    ``list``. This function can be used as a decorator.
     """
     method.__doc__ = getattr(list, method.__name__).__doc__
     return method
@@ -51,10 +49,9 @@ class SmartList(list):
     list (such as the addition, removal, or replacement of elements) will be
     reflected in the sublist, or vice-versa, to the greatest degree possible.
     This is implemented by having sublists - instances of the
-    :py:class:`~mwparserfromhell.smart_list._ListProxy` type - dynamically
-    determine their elements by storing their slice info and retrieving that
-    slice from the parent. Methods that change the size of the list also change
-    the slice info. For example::
+    :py:class:`~._ListProxy` type - dynamically determine their elements by
+    storing their slice info and retrieving that slice from the parent. Methods
+    that change the size of the list also change the slice info. For example::
 
         >>> parent = SmartList([0, 1, 2, 3])
         >>> parent
@@ -183,10 +180,9 @@ def sort(self, cmp=None, key=None, reverse=None):
 class _ListProxy(list):
     """Implement the ``list`` interface by getting elements from a parent.
 
-    This is created by a :py:class:`~mwparserfromhell.smart_list.SmartList`
-    object when slicing. It does not actually store the list at any time;
-    instead, whenever the list is needed, it builds it dynamically using the
-    :py:meth:`_render` method.
+    This is created by a :py:class:`~.SmartList` object when slicing. It does
+    not actually store the list at any time; instead, whenever the list is
+    needed, it builds it dynamically using the :py:meth:`_render` method.
     """
 
     def __init__(self, parent, sliceinfo):

mwparserfromhell/string_mixin.py

@@ -21,9 +21,8 @@
 # SOFTWARE.
 
 """
-This module contains the :py:class:`~mwparserfromhell.string_mixin.StringMixIn`
-type, which implements the interface for the ``unicode`` type (``str`` on py3k)
-in a dynamic manner.
+This module contains the :py:class:`~.StringMixIn` type, which implements the
+interface for the ``unicode`` type (``str`` on py3k) in a dynamic manner.
 """
 
 from __future__ import unicode_literals
@@ -35,9 +34,8 @@
 def inheritdoc(method):
     """Set __doc__ of *method* to __doc__ of *method* in its parent class.
 
-    Since this is used on
-    :py:class:`~mwparserfromhell.string_mixin.StringMixIn`, the "parent class"
-    used is ``str``. This function can be used as a decorator.
+    Since this is used on :py:class:`~.StringMixIn`, the "parent class" used is
+    ``str``. This function can be used as a decorator.
     """
     method.__doc__ = getattr(str, method.__name__).__doc__
     return method

mwparserfromhell/utils.py

@@ -33,20 +33,16 @@
 from .smart_list import SmartList
 
 def parse_anything(value):
-    """Return a :py:class:`~mwparserfromhell.wikicode.Wikicode` for *value*.
+    """Return a :py:class:`~.Wikicode` for *value*, allowing multiple types.
 
     This differs from :py:func:`mwparserfromhell.parse` in that we accept more
     than just a string to be parsed. Unicode objects (strings in py3k), strings
     (bytes in py3k), integers (converted to strings), ``None``, existing
-    :py:class:`~mwparserfromhell.nodes.Node` or
-    :py:class:`~mwparserfromhell.wikicode.Wikicode` objects, as well as an
+    :py:class:`~.Node` or :py:class:`~.Wikicode` objects, as well as an
     iterable of these types, are supported. This is used to parse input
-    on-the-fly by various methods of
-    :py:class:`~mwparserfromhell.wikicode.Wikicode` and others like
-    :py:class:`~mwparserfromhell.nodes.template.Template`, such as
-    :py:meth:`wikicode.insert() <mwparserfromhell.wikicode.Wikicode.insert>`
-    or setting :py:meth:`template.name
-    <mwparserfromhell.nodes.template.Template.name>`.
+    on-the-fly by various methods of :py:class:`~.Wikicode` and others like
+    :py:class:`~.Template`, such as :py:meth:`wikicode.insert()
+    <.Wikicode.insert>` or setting :py:meth:`template.name <.Template.name>`.
     """
     wikicode = mwparserfromhell.wikicode.Wikicode
     if isinstance(value, wikicode):