search

OSC / ood-documentation

Documentation for Open OnDemand generated using Sphinx
https://osc.github.io/ood-documentation/latest/
MIT License
8 stars 50 forks source link

Upgrade Sphinx To Newer Version #869

Open Oglopf opened 9 months ago

Oglopf commented 9 months ago

With the issues rendering url_for in PR #868 we want to begin work around getting sphinx to a newer version.

Currently we sit on version 1.8 and the sphinx project's current version is 7.3.

Oglopf commented 7 months ago

This is going to be a major change to say the least.

The best bet is to iterate over the sphinx changelog and do major version bumps: 2, then 3, etc. Each jump, we will just have to work through that changelog entry and make the needed updates. This could become pretty tedious and will need coordination between incoming changes as well.

I think the smartest thing for us economically is to wait until after this upcoming release to begin the work. This is because we have a lot of churn at the moment to prepare for the release, and that should not be interfered with.

Rather, after the release we should have some relative stability in the docs to then tackle the version upgrade.

Oglopf commented 7 months ago

Also, once this is all complete, we do have the option to then begin using the markdown extension to start using instead of .rst files which require many more keystrokes for the same goals on average and so reduce productivity compared to makrdown docs which are very fast to build and work in.