Adding upstream version 7.2.6.upstream/7.2.6

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

1 files changed, 354 insertions, 0 deletions

diff --git a/doc/faq.rst b/doc/faq.rst
new file mode 100644
index 0000000..85ccb24
--- /dev/null
+++ b/doc/faq.rst
@@ -0,0 +1,354 @@
+.. _faq:
+
+Sphinx FAQ
+==========
+
+This is a list of Frequently Asked Questions about Sphinx.  Feel free to
+suggest new entries!
+
+How do I...
+-----------
+
+... create PDF files without LaTeX?
+   `rinohtype`_ provides a PDF builder that can be used as a drop-in
+   replacement for the LaTeX builder.
+
+   .. _rinohtype: https://github.com/brechtm/rinohtype
+
+... get section numbers?
+   They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
+   the :rst:dir:`toctree` directive where you want to start numbering.
+
+... customize the look of the built HTML files?
+   Use themes, see :doc:`/usage/theming`.
+
+... add global substitutions or includes?
+   Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.
+
+... display the whole TOC tree in the sidebar?
+   Use the :data:`toctree` callable in a custom layout template, probably in the
+   ``sidebartoc`` block.
+
+... write my own extension?
+   See the :doc:`/development/tutorials/index`.
+
+... convert from my existing docs using MoinMoin markup?
+   The easiest way is to convert to xhtml, then convert `xhtml to reST`_.
+   You'll still need to mark up classes and such, but the headings and code
+   examples come through cleanly.
+
+For many more extensions and other contributed stuff, see the sphinx-contrib_
+repository.
+
+.. _sphinx-contrib: https://github.com/sphinx-contrib/
+
+.. _usingwith:
+
+Using Sphinx with...
+--------------------
+
+Read the Docs
+    `Read the Docs <https://readthedocs.org>`_ is a documentation hosting
+    service based around Sphinx.  They will host sphinx documentation, along
+    with supporting a number of other features including version support, PDF
+    generation, and more. The `Getting Started`_ guide is a good place to start.
+
+Epydoc
+   There's a third-party extension providing an `api role`_ which refers to
+   Epydoc's API docs for a given identifier.
+
+Doxygen
+   Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe
+   <https://github.com/michaeljones/breathe/tree/master>`_.
+
+SCons
+   Glenn Hutchings has written a SCons build script to build Sphinx
+   documentation; it is hosted here:
+   https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html
+
+PyPI
+   Jannis Leidel wrote a `setuptools command
+   <https://pypi.org/project/Sphinx-PyPI-upload/>`_ that automatically
+   uploads Sphinx documentation to the PyPI package documentation area at
+   https://pythonhosted.org/.
+
+GitHub Pages
+   Please add :py:mod:`sphinx.ext.githubpages` to your project.  It allows you
+   to publish your document in GitHub Pages.  It generates helper files for
+   GitHub Pages on building HTML document automatically.
+
+MediaWiki
+   See `sphinx-wiki`_, a project by Kevin Dunn.
+
+   .. _sphinx-wiki: https://bitbucket-archive.softwareheritage.org/projects/ke/kevindunn/sphinx-wiki.html
+
+Google Analytics
+   You can use a custom ``layout.html`` template, like this:
+
+   .. code-block:: html+jinja
+
+      {% extends "!layout.html" %}
+
+      {%- block extrahead %}
+      {{ super() }}
+      <script>
+        var _gaq = _gaq || [];
+        _gaq.push(['_setAccount', 'XXX account number XXX']);
+        _gaq.push(['_trackPageview']);
+      </script>
+      {% endblock %}
+
+      {% block footer %}
+      {{ super() }}
+      <div class="footer">This page uses <a href="https://analytics.google.com/">
+      Google Analytics</a> to collect statistics. You can disable it by blocking
+      the JavaScript coming from www.google-analytics.com.
+      <script>
+        (function() {
+          var ga = document.createElement('script');
+          ga.src = ('https:' == document.location.protocol ?
+                    'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+          ga.setAttribute('async', 'true');
+          document.documentElement.firstChild.appendChild(ga);
+        })();
+      </script>
+      </div>
+      {% endblock %}
+
+
+Google Search
+   To replace Sphinx's built-in search function with Google Search, proceed as
+   follows:
+
+   1. Go to https://cse.google.com/cse/all to create the Google Search code
+      snippet.
+
+   2. Copy the code snippet and paste it into ``_templates/searchbox.html`` in
+      your Sphinx project:
+
+      .. code-block:: html+jinja
+
+         <div>
+            <h3>{{ _('Quick search') }}</h3>
+            <script>
+               (function() {
+                  var cx = '......';
+                  var gcse = document.createElement('script');
+                  gcse.async = true;
+                  gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
+                  var s = document.getElementsByTagName('script')[0];
+                  s.parentNode.insertBefore(gcse, s);
+               })();
+            </script>
+           <gcse:search></gcse:search>
+         </div>
+
+   3. Add ``searchbox.html`` to the :confval:`html_sidebars` configuration value.
+
+.. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
+.. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
+.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py
+
+
+Sphinx vs. Docutils
+-------------------
+
+tl;dr: *docutils* converts reStructuredText to multiple output formats. Sphinx
+builds upon docutils to allow construction of cross-referenced and indexed
+bodies of documentation.
+
+`docutils`__ is a text processing system for converting plain text
+documentation into other, richer formats. As noted in the `docutils
+documentation`__, docutils uses *readers* to read a document, *parsers* for
+parsing plain text formats into an internal tree representation made up of
+different types of *nodes*, and *writers* to output this tree in various
+document formats.  docutils provides parsers for one plain text format -
+`reStructuredText`__ - though other, *out-of-tree* parsers have been
+implemented including Sphinx's :doc:`Markdown parser </usage/markdown>`. On the
+other hand, it provides writers for many different formats including HTML,
+LaTeX, man pages, Open Document Format and XML.
+
+docutils exposes all of its functionality through a variety of `front-end
+tools`__, such as ``rst2html``, ``rst2odt`` and ``rst2xml``. Crucially though,
+all of these tools, and docutils itself, are concerned with individual
+documents.  They don't support concepts such as cross-referencing, indexing of
+documents, or the construction of a document hierarchy (typically manifesting
+in a table of contents).
+
+Sphinx builds upon docutils by harnessing docutils' readers and parsers and
+providing its own :doc:`/usage/builders/index`. As a result, Sphinx wraps some
+of the *writers* provided by docutils. This allows Sphinx to provide many
+features that would simply not be possible with docutils, such as those
+outlined above.
+
+__ https://docutils.sourceforge.io/
+__ https://docutils.sourceforge.io/docs/dev/hacking.html
+__ https://docutils.sourceforge.io/rst.html
+__ https://docutils.sourceforge.io/docs/user/tools.html
+
+
+.. _epub-faq:
+
+Epub info
+---------
+
+The following list gives some hints for the creation of epub files:
+
+* Split the text into several files. The longer the individual HTML files are,
+  the longer it takes the ebook reader to render them.  In extreme cases, the
+  rendering can take up to one minute.
+
+* Try to minimize the markup.  This also pays in rendering time.
+
+* For some readers you can use embedded or external fonts using the CSS
+  ``@font-face`` directive.  This is *extremely* useful for code listings which
+  are often cut at the right margin.  The default Courier font (or variant) is
+  quite wide and you can only display up to 60 characters on a line.  If you
+  replace it with a narrower font, you can get more characters on a line.  You
+  may even use `FontForge <https://fontforge.github.io/>`_ and create
+  narrow variants of some free font.  In my case I get up to 70 characters on a
+  line.
+
+  You may have to experiment a little until you get reasonable results.
+
+* Test the created epubs. You can use several alternatives.  The ones I am aware
+  of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
+  and Bookworm_.  For Bookworm, you can download the source from
+  https://code.google.com/archive/p/threepress and run your own local server.
+
+* Large floating divs are not displayed properly.
+  If they cover more than one page, the div is only shown on the first page.
+  In that case you can copy the :file:`epub.css` from the
+  ``sphinx/themes/epub/static/`` directory to your local ``_static/``
+  directory and remove the float settings.
+
+* Files that are inserted outside of the ``toctree`` directive must be manually
+  included. This sometimes applies to appendixes, e.g. the glossary or
+  the indices.  You can add them with the :confval:`epub_post_files` option.
+
+* The handling of the epub cover page differs from the reStructuredText
+  procedure which automatically resolves image paths and puts the images
+  into the ``_images`` directory.  For the epub cover page put the image in the
+  :confval:`html_static_path` directory and reference it with its full path in
+  the :confval:`epub_cover` config option.
+
+* kindlegen_ command can convert from epub3 resulting file to ``.mobi`` file
+  for Kindle. You can get ``yourdoc.mobi`` under ``_build/epub`` after the
+  following command:
+
+  .. code-block:: bash
+
+     $ make epub
+     $ kindlegen _build/epub/yourdoc.epub
+
+  The kindlegen command doesn't accept documents that have section
+  titles surrounding ``toctree`` directive:
+
+  .. code-block:: rst
+
+     Section Title
+     =============
+
+     .. toctree::
+
+        subdocument
+
+     Section After Toc Tree
+     ======================
+
+  kindlegen assumes all documents order in line, but the resulting document
+  has complicated order for kindlegen::
+
+     ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
+
+  If you get the following error, fix your document structure:
+
+  .. code-block:: none
+
+     Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
+     Error(prcgen):E24001: The table of content could not be built.
+
+.. _Epubcheck: https://github.com/IDPF/epubcheck
+.. _Calibre: https://calibre-ebook.com/
+.. _FBreader: https://fbreader.org/
+.. _Bookworm: https://www.oreilly.com/bookworm/index.html
+.. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
+
+.. _texinfo-faq:
+
+Texinfo info
+------------
+
+There are two main programs for reading Info files, ``info`` and GNU Emacs.  The
+``info`` program has less features but is available in most Unix environments
+and can be quickly accessed from the terminal.  Emacs provides better font and
+color display and supports extensive customization (of course).
+
+.. _texinfo-links:
+
+Displaying Links
+~~~~~~~~~~~~~~~~
+
+One noticeable problem you may encounter with the generated Info files is how
+references are displayed.  If you read the source of an Info file, a reference
+to this section would look like::
+
+    * note Displaying Links: target-id
+
+In the stand-alone reader, ``info``, references are displayed just as they
+appear in the source.  Emacs, on the other-hand, will by default replace
+``*note:`` with ``see`` and hide the ``target-id``.  For example:
+
+    :ref:`texinfo-links`
+
+One can disable generation of the inline references in a document
+with :confval:`texinfo_cross_references`.  That makes
+an info file more readable with stand-alone reader (``info``).
+
+The exact behavior of how Emacs displays references is dependent on the variable
+``Info-hide-note-references``.  If set to the value of ``hide``, Emacs will hide
+both the ``*note:`` part and the ``target-id``.  This is generally the best way
+to view Sphinx-based documents since they often make frequent use of links and
+do not take this limitation into account.  However, changing this variable
+affects how all Info documents are displayed and most do take this behavior
+into account.
+
+If you want Emacs to display Info files produced by Sphinx using the value
+``hide`` for ``Info-hide-note-references`` and the default value for all other
+Info files, try adding the following Emacs Lisp code to your start-up file,
+``~/.emacs.d/init.el``.
+
+.. code-block:: elisp
+
+   (defadvice info-insert-file-contents (after
+                                         sphinx-info-insert-file-contents
+                                         activate)
+     "Hack to make `Info-hide-note-references' buffer-local and
+   automatically set to `hide' iff it can be determined that this file
+   was created from a Texinfo file generated by Docutils or Sphinx."
+     (set (make-local-variable 'Info-hide-note-references)
+          (default-value 'Info-hide-note-references))
+     (save-excursion
+       (save-restriction
+         (widen) (goto-char (point-min))
+         (when (re-search-forward
+                "^Generated by \\(Sphinx\\|Docutils\\)"
+                (save-excursion (search-forward "\x1f" nil t)) t)
+           (set (make-local-variable 'Info-hide-note-references)
+                'hide)))))
+
+
+Notes
+~~~~~
+
+The following notes may be helpful if you want to create Texinfo files:
+
+- Each section corresponds to a different ``node`` in the Info file.
+
+- Colons (``:``) cannot be properly escaped in menu entries and xrefs.
+  They will be replaced with semicolons (``;``).
+
+- Links to external Info files can be created using the somewhat official URI
+  scheme ``info``.  For example::
+
+     info:Texinfo#makeinfo_options