Add Sphinx-based documentation.

docs/Makefile

@@ -0,0 +1,153 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -a -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Momoko.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Momoko.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Momoko"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Momoko"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

docs/_themes/michiko/changes/frameset.html

@@ -0,0 +1,11 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN"
+  "http://www.w3.org/TR/html4/frameset.dtd">
+<html>
+  <head>
+    <title>{% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} &mdash; {{ docstitle }}{% endtrans %}</title>
+  </head>
+  <frameset cols="45%,*">
+    <frame name="main" src="changes.html">
+    <frame name="src" src="about:blank">
+  </frameset>
+</html>

docs/_themes/michiko/changes/rstsource.html

@@ -0,0 +1,15 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+  "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+  <head>
+    <title>{% trans filename=filename, docstitle=docstitle|e %}{{ filename }} &mdash; {{ docstitle }}{% endtrans %}</title>
+    <style type="text/css">
+      .hl { background-color: yellow }
+    </style>
+  </head>
+  <body style="font-size: 90%">
+    <pre>
+      {{ text }}
+    </pre>
+  </body>
+</html>

docs/_themes/michiko/changes/versionchanges.html

@@ -0,0 +1,33 @@
+{% macro entries(changes) %}
+<ul>{% for entry, docname, lineno in changes %}
+<li><a href="rst/{{ docname }}.html#L{{ lineno-10 }}" target="src">{{ entry }}</a></li>
+{% endfor %}</ul>
+{% endmacro -%}
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+  "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+  <head>
+    <link rel="stylesheet" href="default.css">
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <title>{% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} &mdash; {{ docstitle }}{% endtrans %}</title>
+  </head>
+  <body>
+    <div class="document">
+      <div class="body">
+    <h1>{% trans version=version|e %}Automatically generated list of changes in version {{ version }}{% endtrans %}</h1>
+    <h2>{{ _('Library changes') }}</h2>
+    {% for modname, changes in libchanges %}
+    <h4>{{ modname }}</h4>
+    {{ entries(changes) }}
+    {% endfor %}
+    <h2>{{ _('C API changes') }}</h2>
+    {{ entries(apichanges) }}
+    <h2>{{ _('Other changes') }}</h2>
+    {% for (fn, title), changes in otherchanges %}
+    <h4>{{ title }} <span style="font-size: 50%">({{ fn }})</span></h4>
+    {{ entries(changes) }}
+    {% endfor %}
+      </div>
+    </div>
+  </body>
+</html>

docs/_themes/michiko/defindex.html

@@ -0,0 +1,35 @@
+{#
+    basic/defindex.html
+    ~~~~~~~~~~~~~~~~~~~
+
+    Default template for the "index" page.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{% extends "layout.html" %}
+{% set title = _('Overview') %}
+{% block body %}
+  <h1>{{ docstitle|e }}</h1>
+  <p>
+    Welcome! This is
+    {% block description %}the documentation for {{ project|e }}
+    {{ release|e }}{% if last_updated %}, last updated {{ last_updated|e }}{% endif %}{% endblock %}.
+  </p>
+  {% block tables %}
+  <p><strong>{{ _('Indices and tables:') }}</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{{ _('Complete Table of Contents') }}</a><br>
+         <span class="linkdescr">{{ _('lists all sections and subsections') }}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{{ _('Search Page') }}</a><br>
+         <span class="linkdescr">{{ _('search this documentation') }}</span></p>
+    </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">{{ _('Global Module Index') }}</a><br>
+         <span class="linkdescr">{{ _('quick access to all modules') }}</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{{ _('General Index') }}</a><br>
+         <span class="linkdescr">{{ _('all functions, classes, terms') }}</span></p>
+    </td></tr>
+  </table>
+  {% endblock %}
+{% endblock %}

docs/_themes/michiko/domainindex.html

@@ -0,0 +1,46 @@
+{% extends "layout.html" %}
+{% set title = indextitle %}
+{% block extrahead %}
+{{ super() }}
+{% if not embedded and collapse_index %}
+    <script type="text/javascript">
+      DOCUMENTATION_OPTIONS.COLLAPSE_INDEX = true;
+    </script>
+{% endif %}
+{% endblock %}
+{% block body %}
+
+   {%- set groupid = idgen() %}
+
+   <h1>{{ indextitle }}</h1>
+
+   <div class="modindex-jumpbox">
+   {%- for (letter, entries) in content %}
+   <a href="#cap-{{ letter }}"><strong>{{ letter }}</strong></a>
+     {%- if not loop.last %} | {% endif %}
+   {%- endfor %}
+   </div>
+
+   <table class="indextable modindextable" cellspacing="0" cellpadding="2">
+   {%- for letter, entries in content %}
+     <tr class="cap" id="cap-{{ letter }}"><td></td><td>
+       <strong>{{ letter }}</strong></td><td></td></tr>
+     {%- for (name, grouptype, page, anchor, extra, qualifier, description)
+             in entries %}
+     <tr{% if grouptype == 2 %} class="cg-{{ groupid.current() }}"{% endif %}>
+       <td>{% if grouptype == 1 -%}
+         <img src="{{ pathto('_static/minus.png', 1) }}" class="toggler"
+              id="toggle-{{ groupid.next() }}" style="display: none" alt="-" />
+           {%- endif %}</td>
+       <td>{% if grouptype == 2 %}&nbsp;&nbsp;&nbsp;{% endif %}
+       {% if page %}<a href="{{ pathto(page) }}#{{ anchor }}">{% endif -%}
+       <tt class="xref">{{ name|e }}</tt>
+       {%- if page %}</a>{% endif %}
+     {%- if extra %} <em>({{ extra|e }})</em>{% endif -%}
+     </td><td>{% if qualifier %}<strong>{{ qualifier|e }}:</strong>{% endif %}
+       {%- if description %}<em>{{ description|e }}</em>{% endif -%}</td></tr>
+     {%- endfor %}
+   {%- endfor %}
+   </table>
+
+{% endblock %}

docs/_themes/michiko/genindex-single.html

@@ -0,0 +1,65 @@
+{#
+    basic/genindex-single.html
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    Template for a "single" page of a split index.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{% macro indexentries(firstname, links) %}
+  <dt>
+  {%- if links -%}
+    <a href="{{ links[0][1] }}">
+    {%- if links[0][0] %}<strong>{% endif -%}
+    {{ firstname|e }}
+    {%- if links[0][0] %}</strong>{% endif -%}
+    </a>
+
+    {%- for ismain, link in links[1:] -%}
+      , <a href="{{ link }}">{% if ismain %}<strong>{% endif -%}
+      [{{ loop.index }}]
+      {%- if ismain %}</strong>{% endif -%}
+      </a>
+    {%- endfor %}
+  {%- else %}
+    {{ firstname|e }}
+  {%- endif %}
+  </dt>
+{% endmacro %}
+
+{% extends "layout.html" %}
+{% set title = _('Index') %}
+{% block body %}
+
+<h1 id="index">{% trans key=key %}Index &ndash; {{ key }}{% endtrans %}</h1>
+
+<table style="width: 100%" class="indextable"><tr>
+  {%- for column in entries|slice(2) if column %}
+  <td style="width: 33%" valign="top"><dl>
+    {%- for entryname, (links, subitems) in column %}
+      {{ indexentries(entryname, links) }}
+      {%- if subitems %}
+      <dd><dl>
+      {%- for subentryname, subentrylinks in subitems %}
+        {{ indexentries(subentryname, subentrylinks) }}
+      {%- endfor %}
+      </dl></dd>
+      {%- endif -%}
+    {%- endfor %}
+  </dl></td>
+  {%- endfor %}
+</tr></table>
+
+{% endblock %}
+
+{% block sidebarrel %}
+   <h4>Index</h4>
+   <p>{% for key, dummy in genindexentries -%}
+   <a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
+     {% if not loop.last %}| {% endif %}
+   {%- endfor %}</p>
+
+   <p><a href="{{ pathto('genindex-all') }}"><strong>{{ _('Full index on one page') }}</strong></a></p>
+   {{ super() }}
+{% endblock %}