What is generate_indexes.py needed for?

[oscarbenjamin]

I'm looking at migrating from doctr/Travis to actions for updating the dev docs. I've also discussed this here: https://github.com/drdoctr/doctr/issues/351#issuecomment-761619459

It should be straight-forward to switch to Actions but it seems we need the generate_indexes.py script to run and that complicates using the available actions that can deploy to the docs. The script is currently run on Travis when updating the dev docs and also when updating the release docs as part of the release process. It seems to me that the obvious thing to do is to set up an action on this repo that runs generate_indexes.py each time a push is made here. That would simplify things at the other end because it means changes just need to be pushed and this repo will manage itself.

However when I look into the generate_indexes.py script I'm not clear what it's actually doing or if it is really needed.

[asmeurer]

It puts the "dev docs" and "latest docs" links at the top. It used to do all the versions before we removed those. Moving to an actions on this repo would be fine if that ends up being easier. We could also preprocess the html after building before deploying on the sympy side.

[oscarbenjamin]

Do you mean the left hand side bar? Where it says:

Documentation version
SymPy 1.7.1 (latest release)
SymPy 1.8.dev (development version)

That's the only difference I see between a local sphinx build and the hosted docs.

I would have thought that the cleanest thing would be to get sphinx to add that in the sidebar so that no post-processing is needed (although I don't actually know how to do that).

We could also preprocess the html after building before deploying on the sympy side.

That's what generate_indexes.py does isn't it?

It's called by doctr for the dev docs and is called directly in the release script: https://github.com/sympy/sympy/blob/9d610300d8b9b38c66b0e26be642fe7a3e15ef1e/release/update_docs.py#L55-L62

[asmeurer]

Yeah, but the difference is doctr runs the script in the sympy_doc repo, but it could just as easily be run in the sympy repo.

[oscarbenjamin]

Yes, that's a good point. That would also simplify things. Potentially it could be part of the Makefile even.

[asmeurer]

Right now the script reads the HTML to determine what the version is to put in the parentheses, but in the SymPy repo this could easily be determined from the git tags.

[oscarbenjamin]

I also asked earlier on the sphinx-users ML how to get Sphinx to add the links but no response yet: https://groups.google.com/g/sphinx-users/c/3BtC3zttpok

[oscarbenjamin]

I'm about to become extremely busy at work. I hoped to get this done this weekend but now that has passed I probably don't have the capacity to do this.

[oscarbenjamin]

There is an answer now on the Sphinx mailing list:

How about using `html_sidebars`? It allows you to insert custom
sidebar-parts to your pages.
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars

1. Create a partial HTML as a template file
2. Put it template dir on your project (ex. _templates)
3. Check `templates_path` configuration contains above template dir
4. Set up your custom sidebar via `html_sidebars`