search

mesonbuild / meson-python

Meson PEP 517 Python build backend
https://mesonbuild.com/meson-python/
MIT License
118 stars 59 forks source link

readthedocs stuck to old version #522

Closed dnicolodi closed 7 months ago

dnicolodi commented 8 months ago

The documentation at https://meson-python.readthedocs.io/en/latest/ is stuck to some old version of the documentation.

Also, https://meson-python.readthedocs.io/ redirects to the latest documentation, which is the one build from the main branch, not from the latest release. The only other version provided by readthedocs is the stable version (which currently points to version 0.13.2, thus a couple of releases ago). Other than getting the latest version built and uploaded, we should probably make the stable version the default.

Do we really need to rely on readthedocs for the documentation? I think that for the basic needs of the project, using Github Pages would be more than adequate and it would be much easier to make sure that the published documentation stays up to date as the build and upload would be integrated in the CI infrastructure.

rgommers commented 8 months ago

Thanks - I opened gh-523 to patch it up quickly. Also, do you have a RTD account/username? If so, I can add you to the project there.

Do we really need to rely on readthedocs for the documentation? I think that for the basic needs of the project, using Github Pages would be more than adequate and it would be much easier to make sure that the published documentation stays up to date as the build and upload would be integrated in the CI infrastructure.

Maybe easier CI wise, however deployment is also a pain. Using a gh-pages branch within the same repo makes a mess, and deploying to another repo is better (no spurious automated commits in the main repo) but not well-supported by GitHub Actions. And if you want to store the built docs for multiple versions, it gets worse. Hence I'd be inclined to not touch it.

The other issue here is that the notifications on build failures were not enabled for me (they are now), otherwise I would have easily caught this problem.

rgommers commented 8 months ago

Reopening for the "shall we move to Github Pages" part.

dnicolodi commented 8 months ago

I agree that the extra branch was a pain, but that is not needed anymore. See for example https://github.com/dnicolodi/python-siphash24/blob/master/.github/workflows/docs.yml

As for the multiple versions, we are just using "latest" pointing to the main branch (which IMO is the wrong choice) and "stable" pointing to the latest release. I don't think that having the docs for the development version published is useful (building the docs locally is trivial) and having the docs just built for the latest release would be straightforward.

dnicolodi commented 8 months ago

Can we have Read The Docs use the "stable" version by default, instead of "latest"?

dnicolodi commented 8 months ago

Something is still wrong with RTD: https://meson-python.readthedocs.io/en/stable/ still has the documentation for 0.13.2, not 0.15.0.

rgommers commented 8 months ago

Yes, that's easy:

image

0.15.0 doesn't build though (as you noted just now) because it needs the fix from gh-523, so I'd have to recreate it from a new tag, which is annoying.

I agree that the extra branch was a pain, but that is not needed anymore.

Ah, I totally missed that. So it just stores it somewhere under the hood, no branch anywhere? If so, then yes I agree it'd be easier to switch.

rgommers commented 8 months ago

It's possible a switch is fiddly CNAME-wise, since https://mesonbuild.github.io/ redirects to https://mesonbuild.com/.

dnicolodi commented 8 months ago

I think that if we enable Github Pages for this project, it would be served as https://mesonbuild.com/meson-python/ which is not that bad, unless the Meson maintainers have anything against it.

dnicolodi commented 8 months ago

0.15.0 doesn't build though (as you noted just now) because it needs the fix from gh-523, so I'd have to recreate it from a new tag, which is annoying.

Annoying, indeed.

dnicolodi commented 8 months ago

0.15.0 doesn't build though (as you noted just now) because it needs the fix from gh-523, so I'd have to recreate it from a new tag, which is annoying.

I would not see anything wrong in releasing 0.15.1 just to fix the documentation, if we decide to keep using RTD.

rgommers commented 7 months ago

I think that if we enable Github Pages for this project, it would be served as https://mesonbuild.com/meson-python/ which is not that bad, unless the Meson maintainers have anything against it.

It's a nice URL indeed. @jpakkane @eli-schwartz would you be fine with us serving the meson-python docs there?

jpakkane commented 7 months ago

Sure, do you need some conf changes on our side?

rgommers commented 7 months ago

Sure, do you need some conf changes on our side?

Thanks! No conf changes needed: https://mesonbuild.com/meson-python/

rgommers commented 7 months ago

I think we can close this now that the docs are up on GitHub Pages and the metadata is up-to-date as well (xref gh-530). We'll leave the ReadTheDocs docs up for now, since links on PyPI and elsewhere are currently pointing there. Once some time has passed (1-2 releases I'd suggest), we can probably clean that up completely, to not leave outdated docs floating around forever.