Docs: build with Sphinx 5

[adamjstewart]

Companion to pytorch/pytorch#70309. See pytorch/pytorch#60979, pytorch/pytorch#61045, and sphinx-doc/sphinx#9395 for discussion.

I believe the reason that we were previously pinning to Sphinx 3 was because of issues with pytorch_sphinx_theme and Sphinx 4 support, but these seem to have been resolved now. See https://torchgeo.readthedocs.io/ for an example of docs built with pytorch_sphinx_theme and Sphinx 4.

[facebook-github-bot]

💊 CI failures summary and remediations

As of commit d06535e (more details on the Dr. CI page):

---

• 5/5 failures introduced in this PR

---

5 failures not recognized by patterns:

Job	Step	Action
binary_linux_wheel_py3.9_rocm4.2	packaging/build_wheel.sh	🔁 rerun
binary_linux_wheel_py3.8_rocm4.2	packaging/build_wheel.sh	🔁 rerun
binary_linux_wheel_py3.7_rocm4.2	packaging/build_wheel.sh	🔁 rerun
binary_linux_wheel_py3.7_rocm4.3.1	packaging/build_wheel.sh	🔁 rerun
binary_linux_wheel_py3.8_rocm4.3.1	packaging/build_wheel.sh	🔁 rerun

---

This comment was automatically generated by Dr. CI (expand for details).

Please report bugs/suggestions to the (internal) Dr. CI Users group.

Click here to manually regenerate this comment.

[oke-aditya]

Hi @adamjstewart !
Here are the rendered docs with sphinx 4.
https://1090793-73328905-gh.circle-artifacts.com/0/docs/index.html

In case you didn't know You can click on build_docs action and view the artifacts over circleCI.

I might have a finer look this weekend comparing the two :)

[NicolasHug]

Thanks for the PR @adamjstewart . I'll keep an eye on pytorch/pytorch#70309 and merge this one when pytorch/pytorch#70309 is accepted on the pytorch core side.

[adamjstewart]

@NicolasHug pytorch/pytorch#70309 has been merged, so this should be good to go once the tests pass.

[adamjstewart]

CI failures look unrelated, is there a way to rerun the failing test?

[oke-aditya]

Can you merge main branch to this and do a push?. Or click on update branch button in github UI
That will re trigger the CI and make easier to validate docs against latest codebase.

[adamjstewart]

Different error this time. Do I rebase again?

[oke-aditya]

You actually don't need to rebase.
Can you try fast forwarding by simplying doing git pull upstream main.
If it can't fast forward you would need to rebase :( .

Btw the docs are visible over

https://output.circle-artifacts.com/output/job/9d7975ec-5efc-4b4e-bcfb-e44948bb938e/artifacts/0/docs/index.html

I'm having a look

[oke-aditya]

OK so it looks great with Sphinx 5. Some bugs are fixed. Mostly the font size looks bold (and better)

Visible difference in font and layout

Old

https://pytorch.org/vision/main/models.html#initializing-pre-trained-models

New

https://output.circle-artifacts.com/output/job/9d7975ec-5efc-4b4e-bcfb-e44948bb938e/artifacts/0/docs/models.html#initializing-pre-trained-models

Old

New

While a good thing is that the improper graying has gone. On the flip side nice contrast of each thumbnail has vanished

Apart from that @adamjstewart do you know what are some features that we could use with sphinx 5?

[adamjstewart]

From looking at the Changelog it seems most of the changes in Sphinx 4 and 5 are changes to defaults in autodoc. For me, the main reason to upgrade to modern Sphinx is bugfixes for issues like pytorch/pytorch#60979. Also see sphinx-doc/sphinx#9395.

[adamjstewart]

You actually don't need to rebase. Can you try fast forwarding by simplying doing git pull upstream main. If it can't fast forward you would need to rebase :( .

Both have the same result, it's just a difference of whether there's a merge commit added or not.

[oke-aditya]

I don't see any error with the branch. Just that it's out of date with main branch. Rest all looks great 😀.

Somehow I prefer merge commit over rebase. Maybe a personal choice.

[adamjstewart]

Seems like the tests are also failing on main...

[NicolasHug]

The docs look fine although slightly worse IMO. But it's probably best to align with torch core to avoid integration issues.
Thanks for the PR @adamjstewart , LGTM