Adding upstream version 5.3.0.upstream/5.3.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

7 files changed, 997 insertions, 0 deletions

diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
new file mode 100644
index 0000000..ccdb6e9
--- /dev/null
+++ b/doc/usage/advanced/intl.rst
@@ -0,0 +1,348 @@
+.. _intl:
+
+Internationalization
+====================
+
+.. versionadded:: 1.1
+
+Complementary to translations provided for Sphinx-generated messages such as
+navigation bars, Sphinx provides mechanisms facilitating the translation of
+*documents*.  See the :ref:`intl-options` for details on configuration.
+
+.. figure:: /_static/translation.*
+   :width: 100%
+
+   Workflow visualization of translations in Sphinx.  (The figure is created by
+   `plantuml <https://plantuml.com>`_.)
+
+.. contents::
+   :local:
+
+Sphinx internationalization details
+-----------------------------------
+
+**gettext** [1]_ is an established standard for internationalization and
+localization.  It naively maps messages in a program to a translated string.
+Sphinx uses these facilities to translate whole documents.
+
+Initially project maintainers have to collect all translatable strings (also
+referred to as *messages*) to make them known to translators.  Sphinx extracts
+these through invocation of ``sphinx-build -b gettext``.
+
+Every single element in the doctree will end up in a single message which
+results in lists being equally split into different chunks while large
+paragraphs will remain as coarsely-grained as they were in the original
+document.  This grants seamless document updates while still providing a little
+bit of context for translators in free-text passages.  It is the maintainer's
+task to split up paragraphs which are too large as there is no sane automated
+way to do that.
+
+After Sphinx successfully ran the
+:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a
+collection of ``.pot`` files in your output directory.  These are **catalog
+templates** and contain messages in your original language *only*.
+
+They can be delivered to translators which will transform them to ``.po`` files
+--- so called **message catalogs** --- containing a mapping from the original
+messages to foreign-language strings.
+
+*gettext* compiles them into a binary format known as **binary catalogs**
+through :program:`msgfmt` for efficiency reasons.  If you make these files
+discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
+will pick them up automatically.
+
+An example: you have a document ``usage.rst`` in your Sphinx project.  The
+*gettext* builder will put its messages into ``usage.pot``.  Imagine you have
+Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
+be translated you need to follow these instructions:
+
+* Compile your message catalog to a locale directory, say ``locale``, so it
+  ends up in ``./locale/es/LC_MESSAGES/usage.mo`` in your source directory
+  (where ``es`` is the language code for Spanish.) ::
+
+        msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
+
+* Set :confval:`locale_dirs` to ``["locale/"]``.
+* Set :confval:`language` to ``es`` (also possible via
+  :option:`-D <sphinx-build -D>`).
+* Run your desired build.
+
+
+In order to protect against mistakes, a warning is emitted if
+cross-references in the translated paragraph do not match those from the
+original.  This can be turned off globally using the
+:confval:`suppress_warnings` configuration variable.  Alternatively, to
+turn it off for one message only, end the message with ``#noqa`` like
+this::
+
+   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
+   risus tortor, luctus id ultrices at. #noqa
+
+(Write ``\#noqa`` in case you want to have "#noqa" literally in the
+text.  This does not apply to code blocks, where ``#noqa`` is ignored
+because code blocks do not contain references anyway.)
+
+.. versionadded:: 4.5
+   The ``#noqa`` mechanism.
+
+
+Translating with sphinx-intl
+----------------------------
+
+Quick guide
+~~~~~~~~~~~
+
+`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.  This
+section describe an easy way to translate with *sphinx-intl*.
+
+#. Install `sphinx-intl`_.
+
+   .. code-block:: console
+
+      $ pip install sphinx-intl
+
+#. Add configurations to ``conf.py``.
+
+   ::
+
+      locale_dirs = ['locale/']   # path is example but recommended.
+      gettext_compact = False     # optional.
+
+   This case-study assumes that BUILDDIR is set to ``_build``,
+   :confval:`locale_dirs` is set to ``locale/`` and :confval:`gettext_compact`
+   is set to ``False`` (the Sphinx document is already configured as such).
+
+#. Extract translatable messages into pot files.
+
+   .. code-block:: console
+
+      $ make gettext
+
+   The generated pot files will be placed in the ``_build/gettext`` directory.
+
+#. Generate po files.
+
+   We'll use the pot files generated in the above step.
+
+   .. code-block:: console
+
+      $ sphinx-intl update -p _build/gettext -l de -l ja
+
+   Once completed, the generated po files will be placed in the below
+   directories:
+
+   * ``./locale/de/LC_MESSAGES/``
+   * ``./locale/ja/LC_MESSAGES/``
+
+#. Translate po files.
+
+   As noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
+   directory.  An example of one such file, from Sphinx, ``builders.po``, is
+   given below.
+
+   .. code-block:: po
+
+      # a5600c3d2e3d48fc8c261ea0284db79b
+      #: ../../builders.rst:4
+      msgid "Available builders"
+      msgstr "<FILL HERE BY TARGET LANGUAGE>"
+
+   Another case, msgid is multi-line text and contains reStructuredText syntax:
+
+   .. code-block:: po
+
+      # 302558364e1d41c69b3277277e34b184
+      #: ../../builders.rst:9
+      msgid ""
+      "These are the built-in Sphinx builders. More builders can be added by "
+      ":ref:`extensions <extensions>`."
+      msgstr ""
+      "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
+      "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
+
+   Please be careful not to break reST notation.  Most po-editors will help you
+   with that.
+
+#. Build translated document.
+
+   You need a :confval:`language` parameter in ``conf.py`` or you may also
+   specify the parameter on the command line.
+
+   For for BSD/GNU make, run:
+
+   .. code-block:: console
+
+      $ make -e SPHINXOPTS="-D language='de'" html
+
+   For Windows :command:`cmd.exe`, run:
+
+   .. code-block:: console
+
+      > set SPHINXOPTS=-D language=de
+      > .\make.bat html
+
+   For PowerShell, run:
+
+   .. code-block:: console
+
+      > Set-Item env:SPHINXOPTS "-D language=de"
+      > .\make.bat html
+
+Congratulations! You got the translated documentation in the ``_build/html``
+directory.
+
+.. versionadded:: 1.3
+
+   :program:`sphinx-build` that is invoked by make command will build po files
+   into mo files.
+
+   If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
+   command before :command:`make` command.
+
+Translating
+~~~~~~~~~~~
+
+Update your po files by new pot files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a document is updated, it is necessary to generate updated pot files and to
+apply differences to translated po files.  In order to apply the updates from a
+pot file to the po file, use the :command:`sphinx-intl update` command.
+
+.. code-block:: console
+
+   $ sphinx-intl update -p _build/gettext
+
+
+Using Transifex service for team translation
+--------------------------------------------
+
+Transifex_ is one of several services that allow collaborative translation via a
+web interface.  It has a nifty Python-based command line client that makes it
+easy to fetch and push translations.
+
+.. TODO: why use transifex?
+
+
+#. Install `transifex-client`_.
+
+   You need :command:`tx` command to upload resources (pot files).
+
+   .. code-block:: console
+
+      $ pip install transifex-client
+
+   .. seealso:: `Transifex Client documentation`_
+
+#. Create your transifex_ account and create new project for your document.
+
+   Currently, transifex does not allow for a translation project to have more
+   than one version of the document, so you'd better include a version number in
+   your project name.
+
+   For example:
+
+   :Project ID: ``sphinx-document-test_1_0``
+   :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
+
+#. Create config files for :command:`tx` command.
+
+   This process will create ``.tx/config`` in the current directory, as well as
+   a ``~/.transifexrc`` file that includes auth information.
+
+   .. code-block:: console
+
+      $ tx init
+      Creating .tx folder...
+      Transifex instance [https://www.transifex.com]:
+      ...
+      Please enter your transifex username: <transifex-username>
+      Password: <transifex-password>
+      ...
+      Done.
+
+#. Upload pot files to transifex service.
+
+   Register pot files to ``.tx/config`` file:
+
+   .. code-block:: console
+
+      $ cd /your/document/root
+      $ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
+        --transifex-project-name sphinx-document-test_1_0
+
+   and upload pot files:
+
+   .. code-block:: console
+
+      $ tx push -s
+      Pushing translations for resource sphinx-document-test_1_0.builders:
+      Pushing source file (locale/pot/builders.pot)
+      Resource does not exist.  Creating...
+      ...
+      Done.
+
+#. Forward the translation on transifex.
+
+   .. TODO: write this section
+
+#. Pull translated po files and make translated HTML.
+
+   Get translated catalogs and build mo files. For example, to build mo files
+   for German (de):
+
+   .. code-block:: console
+
+      $ cd /your/document/root
+      $ tx pull -l de
+      Pulling translations for resource sphinx-document-test_1_0.builders (...)
+       -> de: locale/de/LC_MESSAGES/builders.po
+      ...
+      Done.
+
+   Invoke :command:`make html` (for BSD/GNU make):
+
+   .. code-block:: console
+
+      $ make -e SPHINXOPTS="-D language='de'" html
+
+That's all!
+
+.. tip:: Translating locally and on Transifex
+
+   If you want to push all language's po files, you can be done by using
+   :command:`tx push -t` command.  Watch out! This operation overwrites
+   translations in transifex.
+
+   In other words, if you have updated each in the service and local po files,
+   it would take much time and effort to integrate them.
+
+
+Contributing to Sphinx reference translation
+--------------------------------------------
+
+The recommended way for new contributors to translate Sphinx reference is to
+join the translation team on Transifex.
+
+There is a `sphinx translation page`_ for Sphinx (master) documentation.
+
+1. Login to transifex_ service.
+2. Go to `sphinx translation page`_.
+3. Click ``Request language`` and fill form.
+4. Wait acceptance by transifex sphinx translation maintainers.
+5. (After acceptance) Translate on transifex.
+
+Detail is here: https://docs.transifex.com/getting-started-1/translators
+
+.. rubric:: Footnotes
+
+.. [1] See the `GNU gettext utilities
+       <https://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
+       for details on that software suite.
+.. [2] Because nobody expects the Spanish Inquisition!
+
+.. _`transifex-client`: https://pypi.org/project/transifex-client/
+.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
+.. _Transifex: https://www.transifex.com/
+.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
+.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/
diff --git a/doc/usage/advanced/setuptools.rst b/doc/usage/advanced/setuptools.rst
new file mode 100644
index 0000000..672d658
--- /dev/null
+++ b/doc/usage/advanced/setuptools.rst
@@ -0,0 +1,200 @@
+.. _setuptools:
+
+Setuptools integration
+======================
+
+Sphinx supports integration with setuptools and distutils through a custom
+command - :class:`~sphinx.setup_command.BuildDoc`.
+
+.. deprecated:: 5.0
+
+   This feature will be removed in v7.0.
+
+Using setuptools integration
+----------------------------
+
+The Sphinx build can then be triggered from distutils, and some Sphinx
+options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's own
+configuration file.
+
+For instance, from ``setup.py``::
+
+    # this is only necessary when not using setuptools/distribute
+    from sphinx.setup_command import BuildDoc
+    cmdclass = {'build_sphinx': BuildDoc}
+
+    name = 'My project'
+    version = '1.2'
+    release = '1.2.0'
+    setup(
+        name=name,
+        author='Bernard Montgomery',
+        version=release,
+        cmdclass=cmdclass,
+        # these are optional and override conf.py settings
+        command_options={
+            'build_sphinx': {
+                'project': ('setup.py', name),
+                'version': ('setup.py', version),
+                'release': ('setup.py', release),
+                'source_dir': ('setup.py', 'doc')}},
+    )
+
+.. note::
+
+    If you set Sphinx options directly in the ``setup()`` command, replace
+    hyphens in variable names with underscores. In the example above,
+    ``source-dir`` becomes ``source_dir``.
+
+Or add this section in ``setup.cfg``::
+
+    [build_sphinx]
+    project = 'My project'
+    version = 1.2
+    release = 1.2.0
+    source-dir = 'doc'
+
+Once configured, call this by calling the relevant command on ``setup.py``::
+
+    $ python setup.py build_sphinx
+
+Options for setuptools integration
+----------------------------------
+
+.. setuptools-confval:: fresh-env
+
+   A boolean that determines whether the saved environment should be discarded
+   on build. Default is false.
+
+   This can also be set by passing the `-E` flag to ``setup.py``:
+
+   .. code-block:: console
+
+      $ python setup.py build_sphinx -E
+
+.. setuptools-confval:: all-files
+
+   A boolean that determines whether all files should be built from scratch.
+   Default is false.
+
+   This can also be set by passing the `-a` flag to ``setup.py``:
+
+   .. code-block:: console
+
+      $ python setup.py build_sphinx -a
+
+.. setuptools-confval:: source-dir
+
+   The target source directory. This can be relative to the ``setup.py`` or
+   ``setup.cfg`` file, or it can be absolute.  It defaults to ``./doc`` or
+   ``./docs`` if either contains a file named ``conf.py`` (checking ``./doc``
+   first); otherwise it defaults to the current directory.
+
+   This can also be set by passing the `-s` flag to ``setup.py``:
+
+   .. code-block:: console
+
+      $ python setup.py build_sphinx -s $SOURCE_DIR
+
+.. setuptools-confval:: build-dir
+
+   The target build directory. This can be relative to the ``setup.py`` or
+   ``setup.cfg`` file, or it can be absolute. Default is ``./build/sphinx``.
+
+.. setuptools-confval:: config-dir
+
+   Location of the configuration directory. This can be relative to the
+   ``setup.py`` or ``setup.cfg`` file, or it can be absolute. Default is to use
+   `source-dir`.
+
+   This can also be set by passing the `-c` flag to ``setup.py``:
+
+   .. code-block:: console
+
+      $ python setup.py build_sphinx -c $CONFIG_DIR
+
+   .. versionadded:: 1.0
+
+.. setuptools-confval:: builder
+
+   The builder or list of builders to use. Default is ``html``.
+
+   This can also be set by passing the `-b` flag to ``setup.py``:
+
+   .. code-block:: console
+
+      $ python setup.py build_sphinx -b $BUILDER
+
+   .. versionchanged:: 1.6
+      This can now be a comma- or space-separated list of builders
+
+.. setuptools-confval:: warning-is-error
+
+   A boolean that ensures Sphinx warnings will result in a failed build.
+   Default is false.
+
+   This can also be set by passing the `-W` flag to ``setup.py``:
+
+   .. code-block:: console
+
+      $ python setup.py build_sphinx -W
+
+   .. versionadded:: 1.5
+
+.. setuptools-confval:: project
+
+   The documented project's name. Default is ``''``.
+
+   .. versionadded:: 1.0
+
+.. setuptools-confval:: version
+
+   The short X.Y version. Default is ``''``.
+
+   .. versionadded:: 1.0
+
+.. setuptools-confval:: release
+
+   The full version, including alpha/beta/rc tags. Default is ``''``.
+
+   .. versionadded:: 1.0
+
+.. setuptools-confval:: today
+
+   How to format the current date, used as the replacement for ``|today|``.
+   Default is ``''``.
+
+   .. versionadded:: 1.0
+
+.. setuptools-confval:: link-index
+
+   A boolean that ensures index.html will be linked to the root doc. Default
+   is false.
+
+   This can also be set by passing the `-i` flag to ``setup.py``:
+
+   .. code-block:: console
+
+      $ python setup.py build_sphinx -i
+
+   .. versionadded:: 1.0
+
+.. setuptools-confval:: copyright
+
+   The copyright string. Default is ``''``.
+
+   .. versionadded:: 1.3
+
+.. setuptools-confval:: nitpicky
+
+   Run in nit-picky mode.  Currently, this generates warnings for all missing
+   references.  See the config value :confval:`nitpick_ignore` for a way to
+   exclude some references as "known missing".
+
+   .. versionadded:: 1.8
+
+.. setuptools-confval:: pdb
+
+   A boolean to configure ``pdb`` on exception. Default is false.
+
+   .. versionadded:: 1.5
diff --git a/doc/usage/advanced/websupport/api.rst b/doc/usage/advanced/websupport/api.rst
new file mode 100644
index 0000000..79b51ee
--- /dev/null
+++ b/doc/usage/advanced/websupport/api.rst
@@ -0,0 +1,80 @@
+.. _websupportapi:
+
+.. currentmodule:: sphinxcontrib.websupport
+
+The WebSupport Class
+====================
+
+.. class:: WebSupport
+
+   The main API class for the web support package.  All interactions with the
+   web support package should occur through this class.
+
+   The class takes the following keyword arguments:
+
+   srcdir
+      The directory containing reStructuredText source files.
+
+   builddir
+      The directory that build data and static files should be placed in.  This
+      should be used when creating a :class:`WebSupport` object that will be
+      used to build data.
+
+   datadir
+      The directory that the web support data is in.  This should be used when
+      creating a :class:`WebSupport` object that will be used to retrieve data.
+
+   search
+       This may contain either a string (e.g. 'xapian') referencing a built-in
+       search adapter to use, or an instance of a subclass of
+       :class:`~.search.BaseSearch`.
+
+   storage
+       This may contain either a string representing a database uri, or an
+       instance of a subclass of :class:`~.storage.StorageBackend`.  If this is
+       not provided, a new sqlite database will be created.
+
+   moderation_callback
+       A callable to be called when a new comment is added that is not
+       displayed.  It must accept one argument: a dictionary representing the
+       comment that was added.
+
+   staticdir
+       If the static files should be created in a different location
+       **and not in** ``'/static'``, this should be a string with the name of
+       that location (e.g. ``builddir + '/static_files'``).
+
+       .. note::
+           If you specify ``staticdir``, you will typically want to adjust
+           ``staticroot`` accordingly.
+
+   staticroot
+       If the static files are not served from ``'/static'``, this should be a
+       string with the name of that location (e.g. ``'/static_files'``).
+
+   docroot
+       If the documentation is not served from the base path of a URL, this
+       should be a string specifying that path (e.g. ``'docs'``).
+
+
+.. versionchanged:: 1.6
+
+   WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport.
+   Please add ``sphinxcontrib-websupport`` package in your dependency and use
+   moved class instead.
+
+
+Methods
+-------
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.build
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.get_document
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.get_data
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.add_comment
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.process_vote
+
+.. automethod:: sphinxcontrib.websupport.WebSupport.get_search_results
diff --git a/doc/usage/advanced/websupport/index.rst b/doc/usage/advanced/websupport/index.rst
new file mode 100644
index 0000000..0816640
--- /dev/null
+++ b/doc/usage/advanced/websupport/index.rst
@@ -0,0 +1,16 @@
+.. _websupport:
+
+Sphinx Web Support
+==================
+
+.. versionadded:: 1.1
+
+Sphinx provides a Python API to easily integrate Sphinx documentation into your
+web application.  To learn more read the :ref:`websupportquickstart`.
+
+.. toctree::
+
+   quickstart
+   api
+   searchadapters
+   storagebackends
diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
new file mode 100644
index 0000000..5fa5b00
--- /dev/null
+++ b/doc/usage/advanced/websupport/quickstart.rst
@@ -0,0 +1,255 @@
+.. _websupportquickstart:
+
+Web Support Quick Start
+=======================
+
+Building Documentation Data
+----------------------------
+
+To make use of the web support package in your application you'll need to build
+the data it uses.  This data includes pickle files representing documents,
+search indices, and node data that is used to track where comments and other
+things are in a document.  To do this you will need to create an instance of the
+:class:`~.WebSupport` class and call its :meth:`~.WebSupport.build` method::
+
+   from sphinxcontrib.websupport import WebSupport
+
+   support = WebSupport(srcdir='/path/to/rst/sources/',
+                        builddir='/path/to/build/outdir',
+                        search='xapian')
+
+   support.build()
+
+This will read reStructuredText sources from ``srcdir`` and place the necessary
+data in ``builddir``.  The ``builddir`` will contain two sub-directories: one
+named "data" that contains all the data needed to display documents, search
+through documents, and add comments to documents.  The other directory will be
+called "static" and contains static files that should be served from "/static".
+
+.. note::
+
+   If you wish to serve static files from a path other than "/static", you can
+   do so by providing the *staticdir* keyword argument when creating the
+   :class:`~.WebSupport` object.
+
+
+Integrating Sphinx Documents Into Your Webapp
+----------------------------------------------
+
+Now that the data is built, it's time to do something useful with it.  Start off
+by creating a :class:`~.WebSupport` object for your application::
+
+   from sphinxcontrib.websupport import WebSupport
+
+   support = WebSupport(datadir='/path/to/the/data',
+                        search='xapian')
+
+You'll only need one of these for each set of documentation you will be working
+with.  You can then call its :meth:`~.WebSupport.get_document` method to access
+individual documents::
+
+   contents = support.get_document('contents')
+
+This will return a dictionary containing the following items:
+
+* **body**: The main body of the document as HTML
+* **sidebar**: The sidebar of the document as HTML
+* **relbar**: A div containing links to related documents
+* **title**: The title of the document
+* **css**: Links to CSS files used by Sphinx
+* **script**: JavaScript containing comment options
+
+This dict can then be used as context for templates.  The goal is to be easy to
+integrate with your existing templating system.  An example using `Jinja2
+<https://jinja.palletsprojects.com/>`_ is:
+
+.. code-block:: html+jinja
+
+   {%- extends "layout.html" %}
+
+   {%- block title %}
+       {{ document.title }}
+   {%- endblock %}
+
+   {% block css %}
+       {{ super() }}
+       {{ document.css|safe }}
+       <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
+   {% endblock %}
+
+   {%- block script %}
+       {{ super() }}
+       {{ document.script|safe }}
+   {%- endblock %}
+
+   {%- block relbar %}
+       {{ document.relbar|safe }}
+   {%- endblock %}
+
+   {%- block body %}
+       {{ document.body|safe }}
+   {%- endblock %}
+
+   {%- block sidebar %}
+       {{ document.sidebar|safe }}
+   {%- endblock %}
+
+
+Authentication
+~~~~~~~~~~~~~~
+
+To use certain features such as voting, it must be possible to authenticate
+users.  The details of the authentication are left to your application.  Once a
+user has been authenticated you can pass the user's details to certain
+:class:`~.WebSupport` methods using the *username* and *moderator* keyword
+arguments.  The web support package will store the username with comments and
+votes.  The only caveat is that if you allow users to change their username you
+must update the websupport package's data::
+
+   support.update_username(old_username, new_username)
+
+*username* should be a unique string which identifies a user, and *moderator*
+should be a boolean representing whether the user has moderation privileges.
+The default value for *moderator* is ``False``.
+
+An example `Flask <https://flask.palletsprojects.com/>`_ function that checks
+whether a user is logged in and then retrieves a document is::
+
+   from sphinxcontrib.websupport.errors import *
+
+   @app.route('/<path:docname>')
+   def doc(docname):
+       username = g.user.name if g.user else ''
+       moderator = g.user.moderator if g.user else False
+       try:
+           document = support.get_document(docname, username, moderator)
+       except DocumentNotFoundError:
+           abort(404)
+       return render_template('doc.html', document=document)
+
+The first thing to notice is that the *docname* is just the request path.  This
+makes accessing the correct document easy from a single view.  If the user is
+authenticated, then the username and moderation status are passed along with the
+docname to :meth:`~.WebSupport.get_document`.  The web support package will then
+add this data to the ``COMMENT_OPTIONS`` that are used in the template.
+
+.. note::
+
+   This only works if your documentation is served from your
+   document root. If it is served from another directory, you will
+   need to prefix the url route with that directory, and give the `docroot`
+   keyword argument when creating the web support object::
+
+      support = WebSupport(..., docroot='docs')
+
+      @app.route('/docs/<path:docname>')
+
+
+Performing Searches
+-------------------
+
+To use the search form built-in to the Sphinx sidebar, create a function to
+handle requests to the URL 'search' relative to the documentation root.  The
+user's search query will be in the GET parameters, with the key `q`.  Then use
+the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
+retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that
+would be like this::
+
+   @app.route('/search')
+   def search():
+       q = request.args.get('q')
+       document = support.get_search_results(q)
+       return render_template('doc.html', document=document)
+
+Note that we used the same template to render our search results as we did to
+render our documents.  That's because :meth:`~.WebSupport.get_search_results`
+returns a context dict in the same format that :meth:`~.WebSupport.get_document`
+does.
+
+
+Comments & Proposals
+--------------------
+
+Now that this is done it's time to define the functions that handle the AJAX
+calls from the script.  You will need three functions.  The first function is
+used to add a new comment, and will call the web support method
+:meth:`~.WebSupport.add_comment`::
+
+   @app.route('/docs/add_comment', methods=['POST'])
+   def add_comment():
+       parent_id = request.form.get('parent', '')
+       node_id = request.form.get('node', '')
+       text = request.form.get('text', '')
+       proposal = request.form.get('proposal', '')
+       username = g.user.name if g.user is not None else 'Anonymous'
+       comment = support.add_comment(text, node_id='node_id',
+                                     parent_id='parent_id',
+                                     username=username, proposal=proposal)
+       return jsonify(comment=comment)
+
+You'll notice that both a ``parent_id`` and ``node_id`` are sent with the
+request. If the comment is being attached directly to a node, ``parent_id``
+will be empty. If the comment is a child of another comment, then ``node_id``
+will be empty. Then next function handles the retrieval of comments for a
+specific node, and is aptly named
+:meth:`~sphinxcontrib.websupport.WebSupport.get_data`::
+
+    @app.route('/docs/get_comments')
+    def get_comments():
+        username = g.user.name if g.user else None
+        moderator = g.user.moderator if g.user else False
+        node_id = request.args.get('node', '')
+        data = support.get_data(node_id, username, moderator)
+        return jsonify(**data)
+
+The final function that is needed will call :meth:`~.WebSupport.process_vote`,
+and will handle user votes on comments::
+
+   @app.route('/docs/process_vote', methods=['POST'])
+   def process_vote():
+       if g.user is None:
+           abort(401)
+       comment_id = request.form.get('comment_id')
+       value = request.form.get('value')
+       if value is None or comment_id is None:
+           abort(400)
+       support.process_vote(comment_id, g.user.id, value)
+       return "success"
+
+
+Comment Moderation
+------------------
+
+By default, all comments added through :meth:`~.WebSupport.add_comment` are
+automatically displayed.  If you wish to have some form of moderation, you can
+pass the ``displayed`` keyword argument::
+
+   comment = support.add_comment(text, node_id='node_id',
+                                 parent_id='parent_id',
+                                 username=username, proposal=proposal,
+                                 displayed=False)
+
+You can then create a new view to handle the moderation of comments.  It
+will be called when a moderator decides a comment should be accepted and
+displayed::
+
+   @app.route('/docs/accept_comment', methods=['POST'])
+   def accept_comment():
+       moderator = g.user.moderator if g.user else False
+       comment_id = request.form.get('id')
+       support.accept_comment(comment_id, moderator=moderator)
+       return 'OK'
+
+Rejecting comments happens via comment deletion.
+
+To perform a custom action (such as emailing a moderator) when a new comment is
+added but not displayed, you can pass callable to the :class:`~.WebSupport`
+class when instantiating your support object::
+
+   def moderation_callback(comment):
+       """Do something..."""
+
+   support = WebSupport(..., moderation_callback=moderation_callback)
+
+The moderation callback must take one argument, which will be the same comment
+dict that is returned by :meth:`add_comment`.
diff --git a/doc/usage/advanced/websupport/searchadapters.rst b/doc/usage/advanced/websupport/searchadapters.rst
new file mode 100644
index 0000000..262d666
--- /dev/null
+++ b/doc/usage/advanced/websupport/searchadapters.rst
@@ -0,0 +1,49 @@
+.. _searchadapters:
+
+.. currentmodule:: sphinxcontrib.websupport.search
+
+Search Adapters
+===============
+
+To create a custom search adapter you will need to subclass the
+:class:`BaseSearch` class.  Then create an instance of the new class and pass
+that as the `search` keyword argument when you create the :class:`~.WebSupport`
+object::
+
+   support = WebSupport(srcdir=srcdir,
+                        builddir=builddir,
+                        search=MySearch())
+
+For more information about creating a custom search adapter, please see the
+documentation of the :class:`BaseSearch` class below.
+
+.. class:: BaseSearch
+
+   Defines an interface for search adapters.
+
+.. versionchanged:: 1.6
+
+   BaseSearch class is moved to sphinxcontrib.websupport.search from
+   sphinx.websupport.search.
+
+Methods
+-------
+
+The following methods are defined in the BaseSearch class. Some methods do not
+need to be overridden, but some (:meth:`~BaseSearch.add_document` and
+:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
+working example, look at the built-in adapter for whoosh.
+
+.. automethod:: BaseSearch.init_indexing
+
+.. automethod:: BaseSearch.finish_indexing
+
+.. automethod:: BaseSearch.feed
+
+.. automethod:: BaseSearch.add_document
+
+.. automethod:: BaseSearch.query
+
+.. automethod:: BaseSearch.handle_query
+
+.. automethod:: BaseSearch.extract_context
diff --git a/doc/usage/advanced/websupport/storagebackends.rst b/doc/usage/advanced/websupport/storagebackends.rst
new file mode 100644
index 0000000..ccb00b6
--- /dev/null
+++ b/doc/usage/advanced/websupport/storagebackends.rst
@@ -0,0 +1,49 @@
+.. _storagebackends:
+
+.. currentmodule:: sphinxcontrib.websupport.storage
+
+Storage Backends
+================
+
+To create a custom storage backend you will need to subclass the
+:class:`StorageBackend` class.  Then create an instance of the new class and
+pass that as the `storage` keyword argument when you create the
+:class:`~.WebSupport` object::
+
+   support = WebSupport(srcdir=srcdir,
+                        builddir=builddir,
+                        storage=MyStorage())
+
+For more information about creating a custom storage backend, please see the
+documentation of the :class:`StorageBackend` class below.
+
+.. class:: StorageBackend
+
+   Defines an interface for storage backends.
+
+.. versionchanged:: 1.6
+
+   StorageBackend class is moved to sphinxcontrib.websupport.storage from
+   sphinx.websupport.storage.
+
+
+Methods
+-------
+
+.. automethod:: StorageBackend.pre_build
+
+.. automethod:: StorageBackend.add_node
+
+.. automethod:: StorageBackend.post_build
+
+.. automethod:: StorageBackend.add_comment
+
+.. automethod:: StorageBackend.delete_comment
+
+.. automethod:: StorageBackend.get_data
+
+.. automethod:: StorageBackend.process_vote
+
+.. automethod:: StorageBackend.update_username
+
+.. automethod:: StorageBackend.accept_comment