Fixup packaging requirements

[svenevs]

• Undo the hacks you needed to bypass whatever release of breathe you had to workaround whenever it was (just depend on breathe>=???).
  • Legacy debt: excluding python / sphinx versions.
  • Strategy: do a more permissive release.
  • Followup with updates to README about compatibility notes, pin to latest breathe and implicitly depend on min sphinx / python they support. Do so in a separate release.
• Maybe: remove six.

followup to #179.

[Rotzbua]

I would currently recommend:

• Drop sphinx 3 (Update dependencies according to breathe==4.35.0 #200)
• Drop sphinx 4
• Drop EOL python 3.7

[clalancette]

* Drop sphinx 4

Please don't drop Sphinx 4. It is what is shipped in Ubuntu 22.04, and what we are using to generate our documentation with https://github.com/ros-infrastructure/rosdoc2 .

[Rotzbua]

@clalancette You still can use release 0.3.6, which still works with sphinx 4.

For cross OS interoperability and reproduction pip and venv should be chosen as the installation method for sphinx anyway and not the OS package repository.

Meanwhile sphinx7 is released. In my experience, supporting more than 3 versions of a dependency can quickly become a development hassle.

[svenevs]

We will continue to support jammy until Rosdoc updates. That project contributed heavily to exhale, but the ros ecosystem takes time to update (for good reason). While it may be old, the things exhale has to do with sphinx directly are minimal and we should be able to keep that support around.

I'm hoping to get to this tomorrow and start looking at what can be done to patch this project up for a new release.

[Rotzbua]

According to: https://packages.ubuntu.com/jammy/sphinx-common
No support for sphinx<4.3 required.

[svenevs]

I haven't forgotten about this. I'll be on vacation soon and will be able to carve out some time to give this project a small facelift. Thanks for your patience, I look forward to help testing things 😅

[svenevs]

@clalancette could you please help me understand your minimum requirements?

• https://packages.ubuntu.com/search?suite=jammy&searchon=names&keywords=python3-sphinx
  • Sphinx version: 4.3.2
• https://packages.ubuntu.com/search?suite=jammy&searchon=names&keywords=python3-breathe
  • Breathe version: 4.33.1
  • Currently I require breathe>=4.32.0, it's probably healthy to keep bumping this up over time (?)

I'm planning to require:

• sphinx>=4
  • There was a historical reason why I made the sphinx versions pinned to breathe releases, but I don't even remember it anymore. This project has very very little to do with sphinx directly, the breathe version will constrain as it sees fit since they're the ones emitting nodes. This project dumps the same thing regardless of the breathe version...
• breathe>=4.33.1
  • Pegging the minimum, it would allow sphinx 3 in which is why I'll be pinning sphinx>=4.
• python 3.8+ (EOSL 10/2024)
  • I don't have a good enoug reason to disable it, technically this project still works with 2.7 lol. 3.8 will give me enough shiny new tools to be satisfied.
• Remove docutils. Eventually six.

[Rotzbua]

sphinx>=4

There was a historical reason why I made the sphinx versions pinned to breathe releases, but I don't even remember it anymore. This project has very very little to do with sphinx directly, the breathe version will constrain as it sees fit since they're the ones emitting nodes. This project dumps the same thing regardless of the breathe version...

The early v4.0 v4.1 versions of sphinx are bugged with python3.10.
https://github.com/breathe-doc/breathe/blob/42d731b67d71df05596163554d8dd6815ebe980b/.github/workflows/unit_tests.yml#L22-L30

So I would recommend to not support them, since it normally easy for users to migrate minor versions.