About the documentation
README.md at the project root serves as the:
project home page
PYPI long description
user manual
Design considerations:
Most text is in the README.
Python Package Index long description taken from the README.
README is at the GitHub repository root.
Examples in the README are fully syntax highlighted.
Building a static copy of the documentation for offline use.
No visible raw ReStructured text in the README rendered by GitHub.
Implementation
GitHub pages hosts the project website.
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.md - About the documentation (this page).
api.rst - Development tools API generated by Sphinx autodoc and napoleon.
recent_changes.md
CONTRIBUTING.md
Files
These files are at the project root:
_config.yml
.readthedocs.yml
index.rst
README.md
conf.py
GitHub page build consumes _config.yml.
Since conf.py is at the project root Sphinx searches the entire project for document source files. Additional exclude_patterns keep out unwanted document source files.
The files below in the doc folder are not part of the documentation:
make_wrapped_examples.py
livelog.py
livelog_test_assertion.py
livelog_bad_session.py
Read the Docs hosting
readthedocs.org hosts the Sphinx documentation. doc/requirements.txt lists the build dependencies.