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 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 Maintainers, and for each of “yolile” and “jpmckinney”:
1. Enter the username in Add maintainer
2. Click Add
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 project¶

Application

.readthedocs.yaml¶

version: 2
build:
  os: ubuntu-20.04
  tools:
    python: "3.11"
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-20.04
  tools:
    python: "3.9"
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