Documentation#
Packages and applications must have documentation to describe their usage for an external audience. They may have documentation to describe how to contribute. Documentation is written using Sphinx in a docs
directory.
See also
Note
We can consider writing Architecture Decision Records (ADRs).
Write docstrings#
Packages must have Sphinx-style docstrings for public modules, classes and methods, so that Sphinx can automatically generate documentation and so that Python’s help() function can display useful output.
Use the imperative mood (per PEP 257) in new projects. If an existing project uses the present tense, stay consistent.
Type hints are preferred to type
, rtype
and vartype
fields. Use autodoc_type_aliases to simplify long type hints (related). Use intersphinx_mapping to hyperlink types from other packages. See Type hints.
See also
Build documentation locally#
Install requirements:
pip install furo sphinx-autobuild
Build the HTML pages:
sphinx-autobuild -q docs docs/_build/html --watch .
Open http://127.0.0.1:8000/ in your web browser.
Note
Documentation is built in docs/_build/html
, to match the location when building with make html
from the docs/
directory.
Check docstring style#
Use pydocstyle in new packages.
[build-system]
requires = ["setuptools>=61.2"]
build-backend = "setuptools.build_meta"
[tool.black]
line-length = 119
[tool.isort]
profile = 'black'
line_length = 119
[tool.pydocstyle]
match_dir = '(?!tests).*'
ignore = 'D100,D104,D200,D203,D205,D212,D400,D415'
These error codes are ignored:
- D100 Missing docstring in public module
Avoid generic docstrings for utility modules like
util.py
.- D104 Missing docstring in public package
Document the package in Sphinx, not in
mypackage/__init__.py
.- D200 One-line docstring should fit on one line with quotes
Allow one style for all docstrings. (Make diffs smaller if docstrings change.)
- D203 1 blank line required before class docstring
Incompatible with D211 (No blank lines allowed before class docstring).
- D205 1 blank line required between summary line and description
Allow summary line to be multiple lines, especially if it contains links or roles.
- D212 Multi-line docstring summary should start at the first line
Incompatible with D213 (Multi-line docstring summary should start at the second line).
- D400 First line should end with a period
See D205.
- D415 First line should end with a period, question mark, or exclamation point
Duplicative with D400 (First line should end with a period).
Reference: PEP 257: One-line Docstrings, Multi-line Docstrings
Check broken links#
Sphinx’s linkcheck builder reports redirects, error codes and non-existing anchors. It cannot be configured to report only error codes. As such, it is tedious to include in continuous integration outside OCDS documentation, and to configure for manual invocation.
To check broken links, run:
sphinx-build -q -b linkcheck docs _linkcheck
Review the broken links in the _linkcheck/output.txt
file:
cat _linkcheck/output.txt
Create a ReadTheDocs project#
Sign in to ReadTheDocs
Click Import a Project
Click Import Manually
Enter the name of the repository in Name
Paste the URL of the repository in Repository URL
Enter “main” in Default branch
Check Edit advanced project options
Click Next
Set Programming language to “Python”
Click Finish
Click Admin then Advanced Settings
If the project is a package, check Show version warning
Uncheck Enable PDF build
Uncheck Enable EPUB build
Click Save
Click Admin then Email Notifications
Enter “sysadmin@open-contracting.org” in Email
Click Add
Click Edit Versions (or Versions)
Click Edit for the stable version
Uncheck Active
Click Save
Configure the ReadTheDocs project#
For an application:
.readthedocs.yaml#version: 2 build: os: ubuntu-20.04 tools: python: "3.9" python: install: - requirements: docs/requirements.txt sphinx: fail_on_warning: true
docs/requirements.txt#-r ../requirements.txt furo
For a package:
.readthedocs.yaml#version: 2 build: os: ubuntu-20.04 tools: python: "3.9" python: install: - path: . - requirements: docs/requirements.txt sphinx: fail_on_warning: true
docs/requirements.txt#furo
Note
At present, Python 3.9 is used, because ReadTheDocs is not compatible with Python 3.10.
Redirect a ReadTheDocs project#
Replace
docs/_templates/layout.html
with the below, replacingSUBDOMAIN
:<!DOCTYPE html> <html> <head> <meta charset="utf8"> <meta http-equiv="refresh" content="0; url=https://SUBDOMAIN.readthedocs.io/"> <link rel="canonical" href="https://SUBDOMAIN.readthedocs.io/"> <title>This page has moved</title> </head> <body> <p>This page has moved. Redirecting you to <a href="https://SUBDOMAIN.readthedocs.io/">https://SUBDOMAIN.readthedocs.io/</a>…</p> </body> </html>
Push the change to build the documentation
Sign in to ReadTheDocs
Click on the project
Click Admin
Click Integrations
Click GitHub incoming webhook
Click Delete webhook