Add some initial documentation

1 files changed, 52 insertions, 7 deletions

diff --git a/wikimini/templates/__init__.py b/wikimini/templates/__init__.py
index 533ba5e..6614936 100644
--- a/wikimini/templates/__init__.py
+++ b/wikimini/templates/__init__.py
@@ -1,10 +1,55 @@
-"""Template substitution for Wikimini.
-
-This module contains functions that mimic Wikipedia's templates.
-
-A template is a function that takes the :class:`~wikimini.Wikimini` instance
-and the :class:`~mwparserfromhell.nodes.template.Template` node to convert, and
-returns a string with the template output (see :const:`Template`).
+""" A template in the context of Wikipedia is something like a macro, that is a
+piece of "wikicode" that is included from a different page. Templates on
+Wikipedia are used for semantic markup and to ensure a consistent output across
+Wikipedia pages. For example, the `{{lang-de|...}}
+<https://en.wikipedia.org/wiki/Template:Lang-de>`__ template ensures that the
+text is prefixed with "German:", written in cursive, and has the right
+``lang=de`` HTML attribute applied.
+
+A lot of templates can be ignored when converting from Wikicode to a plain text
+format (e.g. ``{{stub}}``), however some templates are both (relatively) easy
+to mimic (at least in their basic functionality), and contain interesting data
+that we'd like to keep in the output (e.g. ``{{lang|...}}``).
+
+Implementation in Wikimini
+--------------------------
+
+The type of a template is given in :data:`Template`. The type alias is hard to
+digest, so here's a breakdown:
+
+* A template is a function.
+* The function takes as arguments the :class:`~wikimini.Wikimini` instance and
+  the :class:`mwparserfromhell.nodes.Node` that represents the invocation.
+* A template may return either a list of :class:`wikimini.document.Block` or
+  :class:`wikimini.document.Node`, depending on whether the template should
+  expand to block-level constructs (like ``{{blockquote}}``) or to inline text
+  (like ``{{lang}}``).
+
+In order to make your template implementation known to Wikimini, you need to
+register it using :meth:`Registry.insert`. There are multiple possibilities for
+that:
+
+You can either register it in the global registry
+:data:`wikimini.templates.registry`, in which case it will be used by any
+:class:`~wikimini.Wikimini` instance that uses the global registry (which is
+the default).
+
+You can start a new registry using only your own templates by creating one and
+registering all your templates::
+
+    from wikimini.templates import Registry
+    from wikimini.document import Plain
+    from wikimini import Wikimini
+    registry = Registry()
+    registry.insert("lang", lambda _, _:  [Plain("Schnitzel!")])
+
+    wiki = Wikimini(registry=registry)
+
+Alternatively, you can also clone an existing registry using
+:meth:`Registry.copy` and then add templates to it.
+
+Reference
+---------
 """
 import copy
 from typing import Callable, Optional, Union, Sequence