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

Tools

• GitHub Pages
• Sphinx
• myst_parser

myst_parser enables Sphinx to parse Markdown files.

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.