docs: allow TOC navigation

[ulysses4ever]

It annoys me beyond measure that I can't freely browse TOC (in the left sidebar) without jumping between pages. It turned out there's a little switch that allows you to (almost) freely unfold menu items, and I turn it on in this PR.

Why "almost" is because it will still only show one section unfolded at a time. There's a long-standing PR to fix that: readthedocs/sphinx_rtd_theme#692 I think that it's still way better than the current state.

Another related but different idea is to have the TOC fully unfolded always. I'm less sure that I'd want that (perhaps I'd), but sphinx_rtd_theme currently doesn't allow it out of the box: readthedocs/sphinx_rtd_theme#455

Here's what TOC will look like, and you can unfold entries by clicking in [+] without leaving the current page

[ulysses4ever]

Hmm, it doesn't seem to work when rendered… It did work locally.

[andreasabel]

Hmm, it doesn't seem to work when rendered… It did work locally.

Have you checked in the build report that the same package versions are used locally and on rtd?

In case of mismatch, you can upgrade requirements in

cabal/doc/requirements.in

Lines 1 to 5 in 5b64eae

	sphinx >= 3.1
	sphinx_rtd_theme
	sphinx-jsonschema
	# Pygments>=2.7.4 suggested by CVE-2021-20270 CVE-2021-27291
	Pygments >= 2.7.4

and then run make -C doc to generate requirements.txt.
E.g. recently we upgraded to Sphinx >= 5 and sphinx_rtd_theme >= 1 for the Agda docs:

• Fix #5942 (bullet lists in docs) by updating sphinx_rtd_theme agda/agda#5943

[ulysses4ever]

Wow, where do I find these logs normally? I tried to find something like it before but failed miserably: neither docs.readthedocs.io, nor any of GitHub CI links helped (I also googled of course).

These logs have two strange things. First, they mention two versions of sphinx_rtd_theme: 0.4.3 and 1.0.0. Not sure how this works but I definitely hope for 1.0 because that's what I used. And for the record, I used the same doc/requirements.txt! So I hope that it shouldn't be a version mismatch problem.

Second curious thing in the logs, and it looks like the culprit, is that I don't see my patch applied at all! The logs have cat doc/conf.py, which doesn't show the lines I added to conf.py! In particular, after the html_context = ... clause there should be the new html_theme_options = ... clause but there is none. I'm completely lost as to how this is possible...

[andreasabel]

I added a commit that upgrades to Sphinx >= 5.

This seems to trigger new warnings:

WARNING: extlinks: Sphinx-6.0 will require a caption string to contain exactly one '%s' and all other '%' need to be escaped as '%%'.

In the rendered docs, I still do not see a change of behavior (over 3.6) what the TOC concerns.

[ulysses4ever]

Mystery solved: readthedocs/readthedocs.org#1622 i.e. RTD server messes around with conf.py, but there's a workaround, which I added to this patch. I also added a screenshot in the original post for busy reviewers! Otherwise, the preview is at the same place -- now with the changes in effect!

I'm not sure what to do with the warnings introduced with Sphinx update: as we learned, Sphinx version is nor related to the mystery, and the warnings make CI red...

[andreasabel]

I'm not sure what to do with the warnings introduced with Sphinx update:

In my last commit, I am trying to fix this by following the instruction on https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html

P.S.: I checked 2 instances of the rendering of extlinks (e.g.:issue:...), and it looks ok.

[robx]

I think it would be clearer to combine this with the if not on_rtd: block above. E.g.

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_path = [sphinx_rtd_theme.get_html_theme_path()]

[ulysses4ever]

Great catch, thank you! Just did it.

[robx]

Haven't tested it, but the diff look good to me!

[ulysses4ever]

I intend to reshuffle and squash manually such that there are two commits: one about Sphinx update, and one about TOC unfolding. Let me know if you have a better idea.

[ulysses4ever]

Ok, that was a short notice, as I just did the history cleanup. (Old history is still around, right here, if you're curious.)

[fishtreesugar]

👍🏻 https://cabal.readthedocs.io/en/latest looks amazing!