Update sphinx to 4.2.0 (#2261)

* Fix deprecated sphinx method and param names

* Update docs.yml

* Refactor sphinx autosummary patching

* Turn off legacy patch

* Revert "Refactor sphinx autosummary patching"

This reverts commit 02f0455.

* Fix Autosummary patching

* Remove cross ref patch

* Revert "Update docs.yml"

This reverts commit eb8dae7.

* Revert docs.yml changes

* Downgrade to 3.5.4

* Get back to 4.2.0

* Fix ignite theme css

* Add suggestions from code review

* Fix code style

* Revert docs deps

* Fix code snippets line spacing

* Expand Notes section

* Fix function names

* Use empty array for collapsedSections

Author: trsvchn

.github/workflows/docs.yml

@@ -60,7 +60,7 @@ jobs:
 
       - name: make linkcheck
         working-directory: ./docs/
-        run: make linkcheck --jobs 2 SPHINXOPTS="--color -W"
+        run: make linkcheck
 
   doctest:
     if: github.event_name == 'pull_request' || github.event_name == 'push'
@@ -83,6 +83,6 @@ jobs:
       - name: make doctest
         working-directory: ./docs/
         run: |
-          make html SPHINXOPTS="--color -W"
+          make html
           make doctest
           make coverage

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -j auto -WT --keep-going --color
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = ignite
 SOURCEDIR     = source

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx==3.4.3
+sphinx==4.2.0
 -e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme
 sphinxcontrib-katex
 sphinx-copybutton==0.4.0

docs/source/_templates/_static/css/ignite_theme.css

@@ -217,6 +217,23 @@ article.pytorch-article p.rubric {
 }
 
 .highlight pre {
-  border: 1px solid rgba(0,0,0,0.15);
+  border: 1px solid rgba(0, 0, 0, 0.15);
   border-radius: 4px;
+  line-height: 1.375rem;
+}
+
+/* Sphinx >=3.5: Fix class/method/fn names, because of spans */
+article.pytorch-article .class dt > span span.pre,
+article.pytorch-article .function dt > span span.pre {
+  color: inherit;
+  font-size: 87.5%;
+  font-family: IBMPlexMono, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Liberation Mono", "Courier New", monospace;
+}
+
+/* Sphinx >=3.5: Fix annotations */
+article.pytorch-article .class dt span.pre,
+article.pytorch-article .function dt span.pre {
+  color: inherit;
+  padding: 2px 0.2px;
 }

docs/source/_templates/layout.html

@@ -496,7 +496,7 @@ <h2>Resources</h2>
   <script type="text/javascript" src="{{ pathto('_static/js/vendor/anchor.min.js', 1) }}"></script>
 
   <script type="text/javascript">
-    var collapsedSections = ['Notes']
+    var collapsedSections = []
     $(document).ready(function() {
       mobileMenu.bind();
       mobileTOC.bind();

docs/source/conf.py

@@ -16,10 +16,11 @@
 import sys
 
 sys.path.insert(0, os.path.abspath("../.."))
-import ignite
+from datetime import datetime
+
 import pytorch_sphinx_theme
 
-from datetime import datetime
+import ignite
 
 # -- Project information -----------------------------------------------------
 
@@ -133,7 +134,8 @@
 }
 
 html_last_updated_fmt = "%m/%d/%Y, %X"
-html_add_permalinks = "#"
+html_permalinks = True
+html_permalinks_icon = "#"
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -213,26 +215,17 @@
 autodoc_typehints = "description"
 napoleon_attr_annotations = True
 
-# -- A patch that turns-off cross refs for type annotations ------------------
-
-import sphinx.domains.python
-from docutils import nodes
-from sphinx import addnodes
-
-# replaces pending_xref node with desc_type for type annotations
-sphinx.domains.python.type_to_xref = lambda t, e=None: addnodes.desc_type("", nodes.Text(t))
-
 # -- Autosummary patch to get list of a classes, funcs automatically ----------
 
 from importlib import import_module
 from inspect import getmembers, isclass, isfunction
-import sphinx.ext.autosummary
-from sphinx.ext.autosummary import Autosummary
+
 from docutils.parsers.rst import directives
 from docutils.statemachine import StringList
+from sphinx.ext.autosummary import Autosummary
 
 
-class BetterAutosummary(Autosummary):
+class AutolistAutosummary(Autosummary):
     """Autosummary with autolisting for modules.
 
     By default it tries to import all public names (__all__),
@@ -317,9 +310,6 @@ def run(self):
         return super().run()
 
 
-# Patch original Autosummary
-sphinx.ext.autosummary.Autosummary = BetterAutosummary
-
 # --- autosummary config -----------------------------------------------------
 autosummary_generate = True
 
@@ -352,3 +342,7 @@ def run(self):
 
 manual_seed(666)
 """
+
+
+def setup(app):
+    app.add_directive("autosummary", AutolistAutosummary, override=True)