Permalink
Browse files

Simplify docs massively.

  • Loading branch information...
1 parent bdf5608 commit 816207bb5a8d89a340a2266f090cb2bdfd6aceb2 @earwig committed Aug 22, 2012
@@ -7,6 +7,7 @@ nodes Package
.. automodule:: mwparserfromhell.nodes
.. autoclass:: mwparserfromhell.nodes.Node
+ :special-members:
:mod:`heading` Module
---------------------
@@ -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`."
@@ -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()
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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``.
"""
@@ -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
@@ -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):
@@ -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()
@@ -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
@@ -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):
@@ -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
@@ -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):
Oops, something went wrong.

0 comments on commit 816207b

Please sign in to comment.