About the documentation
-----------------------

The documentation is built from a combination of
.md and .rst source files.  Most of the documentation
is sourced from README.md.  To achieve the goals listed
below the documentation root folder is moved from
/doc to the project root.

Goals
~~~~~

The documentation is constructed to achieve:

- Everything in the README.
- Python Package Index long description taken from the README.
- README at the Github repository root.
- Examples in the README are fully syntax highlighted.
- README examples are tested by the test suite.
- Building a static copy of the documentation for offline use.
- No visible raw ReStructured text in the README rendered by Github.

Implementation:

- Github hosts the repository and renders README.md.
- readthedocs.org hosts the HTML and creates the PDF for offline use.
- Nearly everything is in README.md. These aren't:

  - index.rst - Top level of the Sphinx documentation.
  - about.rst - About the documentation (this page).
  - api.rst - Development tools API generated by
    Sphinx autodoc and napoleon.
  - recent_changes.md

Tools
~~~~~

- Sphinx
- recommonmark

recommonmark enables Sphinx to parse Markdown files.

Files
~~~~~

These files are at the project root:

- .readthedocs.yml
- index.rst
- README.md
- conf.py

Since conf.py is at the project root the entire project is
searched by Sphinx for document source files.  Additional
``exclude_patterns`` keep out unwanted document source files.

These files are not part of the documentation.
They are expected values used by the regression test suite.

- doc/test_example1.py
- doc/test_example2.py

Read the Docs hosting
~~~~~~~~~~~~~~~~~~~~~

The Sphinx documentation is hosted by readthedocs.org.
The documentation build dependencies ``doc/requirements.txt`` are
pinned to what is currently available.

(excluded from contents)
~~~~~~~~~~~~~~~~~~~~~~~~

This section is here only to suppress Sphinx WARNING: document isn't
included in any toctree.  These files are referenced from README.md.

   example1.md | example2.md | test_example2.md

.. toctree::
   :maxdepth: 0
   :hidden:

   example1.md
   example2.md
   test_example2.md
