Build online docs (RTD) with -W and dependencies by EliahKagan · Pull Request #1843 · gitpython-developers/GitPython (original) (raw)

Fixes #1840

This configures Read the Docs builds to be more like local builds in two ways:

• Pass -W, as is done in a local build with make -C doc html, so that if there are broken references, the build fails.
• Install dependencies. This configures the Python environment, via the python.install key, so that RTD builds install requirements.

More specifically on dependency installation, it does two things:

1. The equivalent of pip install ., which installs the project and its dependencies (though not any extras). This includes the gitdb dependency, which is needed to import GitPython's git module to populate sections in the API Reference page (#1840).
2. The equivalent of pip install -r doc/requirements.txt, which installs the additional Sphinx-related dependencies used when building documentation locally.

Installing Sphinx-related dependencies is useful for three reasons:

• Least importantly, it should increase consistency between remote (RTD) and local documentation builds.
• It may be needed to avoid warnings that are not being fixed at this time, while still allowing the build to succeed with the -W option (see above on that change) that causes failure for immediately addressable problems. The effect of newer versions of Sphinx carrying a few extra hard-to-fix warnings for GitPython is noted in #1802 (and is why they are not upgraded in #1803).
• One of the documentation build dependencies listed in doc/requirements.txt is sphinx_rtd_theme. In 634151a (for #1794) the line specifying this theme was commented out, since it apparently broke in the build. This may allow it to be used again (or can be replaced with another custom theme if desired).

This also reenables the sphinx_rtd_theme theme disabled in 634151a.

Finally, this makes minor changes to .readthedocs.yml's comments and formatting so the comments are accurate for GitPython details and so the file is formatted in the same style as other YAML here.

I did not test the Read the Docs configuration changes before opening this pull request, so I suspect some changes may be needed. I am looking forward to seeing if pull request builds (#1842) are working and if they reflect changes made to readthedocs.yml such that these changes can be checked.

The only testing I did was to run make -C doc html locally to check that the changes to conf.py didn't break the documentation build and that it had the effect, locally, of restoring that theme. That worked as expected, but it is also the aspect of these changes least in need of testing.