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 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 link types from other packages. See Type annotations.

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 sphinx-autobuild -r docs/requirements.txt

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, like when building with make html from the docs/ directory.

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

ReadTheDocs¶

Create a project¶

Sign in to ReadTheDocs
Click Add project
Click Configure 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. Click Next
Click Finish
Click Settings:
1. Set Programming Language to “Python”
2. Click Save
Click Settings then Maintainers, and for each of “yolile” and “jpmckinney”:
1. Click Add maintainer
2. Enter the username in Email address or username
3. Click Invite
Click Settings then Email notifications
1. Click Add notification
2. Enter “sysadmin@open-contracting.org” in Email
3. Click Save

Configure the project¶

Application

.readthedocs.yaml¶

version: 2
build:
  os: ubuntu-lts-latest
  tools:
    python: "3"
python:
  install:
    - requirements: docs/requirements.txt
sphinx:
  configuration: docs/conf.py
  fail_on_warning: true

docs/requirements.txt¶

-r ../requirements.txt
furo

Package

.readthedocs.yaml¶

version: 2
build:
  os: ubuntu-lts-latest
  tools:
    python: "3"
python:
  install:
    - path: .
    - requirements: docs/requirements.txt
sphinx:
  configuration: docs/conf.py
  fail_on_warning: true

docs/requirements.txt¶

furo

Redirect a 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