setup: Upgrade pinned Sphinx version to v5.1.1 (Issue #492)

[tomtseng]

Changes

We pinned Sphinx to v5.0.2 because v5.1.0 broke for us (issue #492). v5.1.1 fixes the problem, so we can upgrade Sphinx now.

Testing

Running make html in docs/ with Sphinx v5.1.1 doesn't crash:

Running Sphinx v5.1.1
loading pickled environment... done
[autosummary] generating autosummary for: _api/imitation.algorithms.adversarial.airl.rst, _api/imitation.algorithms.adversarial.common.rst, _api/imitation.algorithms.adversarial.gail.rst, _api/imitation.algorithms.adversarial.rst, _api/imitation.algorithms.base.rst, _ap
i/imitation.algorithms.bc.rst, _api/imitation.algorithms.dagger.rst, _api/imitation.algorithms.density.rst, _api/imitation.algorithms.mce_irl.rst, _api/imitation.algorithms.preference_comparisons.rst, ..., development/contributing/code-of-conduct.rst, development/contri
buting/index.rst, development/contributing/ways-to-contribute.rst, development/license.rst, development/release-notes.rst, getting-started/first-steps.rst, getting-started/installation.rst, getting-started/variable-horizon.rst, getting-started/what-is-imitation.rst, ind
ex.rst
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 82 source files that are out of date
updating environment: [config changed ('version')] 82 added, 0 changed, 0 removed
reading sources... [100%] getting-started/what-is-imitation .. index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindex done
highlighting module code... [100%] typing
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

I didn't see anything obviously broken when clicking through some pages in the docs generated from this PR.

[Rocamonde]

I am happy to upgrade to v5.1.1. if the checks are passing, but I suggest that instead of removing the version requirement, we update it. I find that not fixing version numbers in dependencies (at least the major and minor number) is a bad practice and leads to issues like these(#492 and #507) happening. We can allow for patches to automatically install, and then regularly review dependency versions and upgrade them (there are extensions for this -- see Dependabot)

[tomtseng]

Makes sense to me. I've updated the PR to pin to sphinx~=5.1.1.

One concern with pinning dependencies too strictly is that someone who uses imitation along with other libraries may get dependency conflicts, but I don't expect issues with pinning sphinx as it's only used for documentation generation.

[Rocamonde]

That's a fair point. In that case, we could pin only the major version of the packages. Alternatively (or also) have a GitHub workflow/action in place that checks for things breaking when new versions are released, and create a PR excluding that version (by `!=x.y.z`).

…

On Mon, Aug 01, 2022 at 5:17 PM, Tom Tseng < ***@***.*** > wrote: Makes sense to me. I've updated the PR to pin to sphinx~=5.1.1. One concern with pinning dependencies too much is that someone who uses imitation along with other libraries may get dependency conflicts, but I don't expect issues with pinning packages for dev packages like sphinx. — Reply to this email directly, view it on GitHub ( #509 (comment) ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/ABVWH36AFFOMRY3CPB7B4ODVW72BXANCNFSM55H5SLOQ ). You are receiving this because your review was requested. Message ID: <HumanCompatibleAI/imitation/pull/509/c1201416680 @ github. com>

[AdamGleave]

There's definitely a trade-off here in terms of greater reliability vs flexibility on versions. A compromise would be to pin packages that have caused us pain in the past. I think this is the first time Sphinx has broken for us, but we've had issues with flake8 and isort before.

[AdamGleave]

LGTM. (Lint failure unrelated, docs build OK on RDT.)

[codecov]

Codecov Report

Merging #509 (94b1f0f) into master (4deb828) will increase coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #509      +/-   ##
==========================================
+ Coverage   96.82%   96.85%   +0.02%     
==========================================
  Files          82       82              
  Lines        7126     7126              
==========================================
+ Hits         6900     6902       +2     
+ Misses        226      224       -2     

Impacted Files	Coverage Δ
src/imitation/algorithms/dagger.py	100.00% <0.00%> (+0.93%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us.