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

General documentation guide

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.

Note

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

See also

Check docstring style

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

1. Sign in to ReadTheDocs

2. Click Import a Project

3. 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

4. Set Programming language to “Python”

5. Click Finish

6. 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

7. Click Admin then Maintainers, and for each of “yolile” and “jpmckinney”:

   1. Enter the username in Add maintainer

   2. Click Add

8. Click Admin then Email Notifications

   1. Enter “sysadmin@open-contracting.org” in Email

   2. Click Add

9. Click Edit Versions (or Versions)

   1. Click Edit for the stable version

   2. Uncheck Active

   3. Click Save

Configure the ReadTheDocs project

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

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

1. 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>
   

2. Push the change to build the documentation

3. Sign in to ReadTheDocs

4. Click on the project

5. Click Admin

6. Click Integrations

7. Click GitHub incoming webhook

8. Click Delete webhook