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.

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.

Note

Sphinx does not read .pyi files, so all type hints must be in the .py files (issue/pull).

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.

pyproject.toml#

[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
1. Enter the name of the repository in Name
2. Paste the URL of the repository in Repository URL
3. Enter “main” in Default branch
4. Check Edit advanced project options
5. Click Next
Set Programming language to “Python”
Click Finish
Click Admin then Advanced Settings
1. If the project is a package, check Show version warning
2. Uncheck Enable PDF build
3. Uncheck Enable EPUB build
4. Click Save
Click Admin then Email Notifications
1. Enter “sysadmin@open-contracting.org” in Email
2. Click Add
Click Edit Versions (or Versions)
1. Click Edit for the stable version
2. Uncheck Active
3. 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, replacing SUBDOMAIN:

<!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>&hellip;</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