Docs need updating to modern docutils

[lilyminium]

Expected behavior

We should aspire for our documentation to be built with the latest, or near latest, versions of packages.

In #4177 and #4194 the documentation appears to have broken due to our docutils updating from 0.17.1 to 0.18.1. #4196 pins docutils<0.18 but this should be a temporary solution at best. docutils 0.18 actually came out at the end of 2021 and the package is now working on 0.21, so we should look at upgrading.

a963edc#diff-e0e12b88089dbc2e97e54366222048d8d05e4a7ef5efe67f0203a2560f301a72 is a diff of the differences -- it looks like docutils adds more classes and punctuation. The JS has also changed.

We have custom punctuation appended to fields in custom.css, so that's a good place to start fixing things.

[IAlibay]

Can someone take ownership of dealing with this please? Leaving pins in too long effectively just packages a nice landmine for the release manager.

[IAlibay]

Pinging @MDAnalysis/coredevs

[lilyminium]

The new MDA theme I'm working on fixes this. Docs rendered with modern docutils: https://github.com/lilyminium/mdanalysis-sphinx-theme (on private repo while I check rendering on my domain https://minium.com.au/mdanalysis-sphinx-theme/PR5/pymethod.html)

There's still a fair bit of work to do -- docs are still preliminary and I'm still reconciling things between stuff copied from OpenFF and our own theme, as well as fixing things I found along the way -- but outsourcing the docs theme is probably the best solution, instead of fixing individually in every repo.

[orbeckst]

Can you coordinate with Ian about themes? He also started making a theme package for kits. Let‘s not duplicate effort but instead make all our lives easier. Am 8/1/23 um 00:49 schrieb Lily Wang ***@***.***>: The new MDA theme I'm working on fixes this. Docs rendered with modern docutils: https://github.com/lilyminium/mdanalysis-sphinx-theme (on private repo while I check rendering on my domain https://minium.com.au/mdanalysis-sphinx-theme/PR5/pymethod.html) There's still a fair bit of work to do but outsourcing the docs theme is probably the best solution, instead of fixing individually in every repo. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are on a team that was mentioned.Message ID: ***@***.***>

[lilyminium]

Yes, I had reached out yesterday about merging our efforts: https://github.com/MDAnalysis/mda_theme/issues/1 Let me know if there’s a better way to coordinate. On Aug 2, 2023, at 01:35, Oliver Beckstein ***@***.***> wrote: Can you coordinate with Ian about themes? He also started making a theme package for kits. Let‘s not duplicate effort but instead make all our lives easier. Am 8/1/23 um 00:49 schrieb Lily Wang ***@***.***>: The new MDA theme I'm working on fixes this. Docs rendered with modern docutils: https://github.com/lilyminium/mdanalysis-sphinx-theme (on private repo while I check rendering on my domain https://minium.com.au/mdanalysis-sphinx-theme/PR5/pymethod.html) There's still a fair bit of work to do but outsourcing the docs theme is probably the best solution, instead of fixing individually in every repo. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you are on a team that was mentioned.Message ID: ***@***.***> —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were assigned.Message ID: ***@***.***>

[IAlibay]

I will say I'm rather surprised that @ianmkenney has a separate repo here. The agreement (as defined in the notes) from last week's meeting was that @lilyminium would be setting up the repository.

[ianmkenney]

@IAlibay Yeah that's my bad, I hadn't heard anything about it yet and was bored over the weekend late one night and got it working somewhat. @lilyminium and I are meeting soon to figure out what overlap there currently is and how to proceed.

[ianmkenney]

Fortunately, @lilyminium and I were working on two different features and the majority of our work did not overlap. For now we're going to update her repo at https://github.com/lilyminium/mdanalysis-sphinx-theme with the plan to transfer ownership once the rendering looks correct and configuration options are working as expected.