Merge pull request haskell#8196 from ulysses4ever/navigation

docs: allow TOC navigation

doc/conf.py

@@ -28,12 +28,12 @@
 
 # extlinks -- see http://www.sphinx-doc.org/en/stable/ext/extlinks.html
 extlinks = {
-    'issue': ('https://github.com/haskell/cabal/issues/%s', '#'),
+    'issue': ('https://github.com/haskell/cabal/issues/%s', 'issue #%s'),
 
-    'ghc-wiki': ('https://gitlab.haskell.org/ghc/ghc/-/wikis/%s', ''),
-    'ghc-ticket': ('https://gitlab.haskell.org/ghc/ghc/-/issues/%s', 'GHC #'),
+    'ghc-wiki': ('https://gitlab.haskell.org/ghc/ghc/-/wikis/%s', '%s'),
+    'ghc-ticket': ('https://gitlab.haskell.org/ghc/ghc/-/issues/%s', 'GHC issue #%s'),
 
-    'hackage-pkg': ('http://hackage.haskell.org/package/%s', ''),
+    'hackage-pkg': ('http://hackage.haskell.org/package/%s', '%s'),
 }
 
 # General information about the project.
@@ -57,9 +57,13 @@
 # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-if not on_rtd:  # only import and set the theme if we're building docs locally
+html_theme = 'sphinx_rtd_theme'
+# only import the theme if we're building docs locally
+if on_rtd:
+    html_style = None
+    using_rtd_theme = True
+else:
     import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # The name for this set of Sphinx documents.  If None, it defaults to
@@ -81,6 +85,9 @@
     "conf_py_path": "doc/",
     "source_suffix": '.rst',
 }
+html_theme_options = {
+    'collapse_navigation': False,
+}
 
 
 # If true, an OpenSearch description file will be output, and all pages will

doc/requirements.in

@@ -1,5 +1,5 @@
-sphinx >= 3.1
-sphinx_rtd_theme
+sphinx >= 5
+sphinx_rtd_theme >= 1
 sphinx-jsonschema
 # Pygments>=2.7.4 suggested by CVE-2021-20270 CVE-2021-27291
 Pygments >= 2.7.4

doc/requirements.txt

@@ -21,6 +21,8 @@ idna==2.10
     # via requests
 imagesize==1.2.0
     # via sphinx
+importlib-metadata==4.11.4
+    # via sphinx
 jinja2==2.11.3
     # via sphinx
 jsonpointer==2.1
@@ -45,7 +47,7 @@ requests==2.26.0
     #   sphinx-jsonschema
 snowballstemmer==2.1.0
     # via sphinx
-sphinx==4.2.0
+sphinx==5.0.1
     # via
     #   -r requirements.in
     #   sphinx-rtd-theme
@@ -67,6 +69,5 @@ sphinxcontrib-serializinghtml==1.1.5
     # via sphinx
 urllib3==1.26.7
     # via requests
-
-# The following packages are considered to be unsafe in a requirements file:
-# setuptools
+zipp==3.8.0
+    # via importlib-metadata