Consider moving to sphinx-contrib and appointing a second maintainer #88
Comments
|
Also a bit worried about maintenance of this great project. Hopefully this sorts out ❤️ |
|
Since this projects seems to be unmaintained, I started developing sphinx-polyversion (which is such an original name, if you have a better idea pls tell me). The tool probably |
The sphinxcontrib-versioning seems unmaintainted and I can't get the fork that we used before this PR working on Python 3.10. The situation wrt maintenance doesn't seem much better for sphinx-multiversion, but, at least I could get it to work with current sphinx versions. The main drawback of this PR is that we're breaking the default URLs. I.e., `https://zrepl.github.io/configuration.html` will be 404. And since we're on GitHub pages and don't control the webserver, we can't install a redirect easily. The above is not necessarily a show-stopper, but not great either. So, not merging this PR right away but looking into `sphinx-polyversion` as recommended in sphinx-contrib/multiversion#88 (comment) Notes ===== The `requirements.txt` in this PR is from a clean Python 3.10 venv on Ubuntu 22.10 after ``` pip install sphinx sphinx-rtd-theme sphinx-multiversion ```
The sphinxcontrib-versioning seems unmaintainted and I can't get the fork that we used before this PR working on Python 3.10. The situation wrt maintenance doesn't seem much better for sphinx-multiversion, but, at least I could get it to work with current sphinx versions. The main problem with sphinx-multiversion is that it doesn't render anything at `/`. I.e., `https://zrepl.github.io/configuration.html` will be 404. That's different from `sphinxcontrib-versioning`, and thus switching to sphinx-multiversion would break URLs. We host on GitHub pages and don't control the webserver, so, we can't use webserver-level redirects to keep the URLs working. We could create JS-level redirects, or `http-equiv`, but that's ugly as well. The simplest solution was to fork sphinx-multiversion and hard-code zrepl's specific needs into that fork. The fork is based off v0.2.4 and pinned via requirements.txt. Here are its unique commits: sphinx-contrib/multiversion@master...zrepl:sphinx-multiversion:zrepl We should revisit `sphinx-polyversion` in the future once its docs improve. See sphinx-contrib/multiversion#88 (comment) This PR updates the various Python packages, as I couldn't get sphinx-multiversion to work with the (very old) versions that were pinned in `requirements.txt` prior to this PR. This PR's `requirements.txt` is from a clean Python 3.10 venv on Ubuntu 22.10 after running ``` pip install sphinx sphinx-rtd-theme pip install 'git+https://github.com/zrepl/sphinx-multiversion/@52c915d7ad898d9641ec48c8bbccb7d4f079db93#egg=sphinx_multiversion' ```
|
Just a bump here to mention a kudos to the original development efforts by @Holzhaus and others who helped create this project! It really says something that this still works relatively well ~4 years after the latest release. That said, to keep the project maintained it's clear there's a need to add maintainers or move the project to sphinx-contrib as @BurningEnlightenment suggested. @Holzhaus please don't hesitate to let the community know of your thoughts as well on this and thank you for creating the project. |
|
Agreed. Things shouldn't rot! Some much work has been done, and many blog posts / tutorials point here. There will always be a lot of drop off if people come here and don't investigate which forks are actually active. I guess the next best solution would be to update the readme with some community suggestions of successor projects, and just link to them. |
|
Hi, sorry for the long silence from my side. I originally created this project for the Mixxx manual, where it's still actively used. So it still works for me ;-) Unfortunately, my job and other FOSS projects I'm working on currently don't leave enough free time to maintaining this properly and help other people integrate it in more elaborate sphinx setups than mine. In the spirit of free software, I appreciate the forks and I have no concerns or anything to move this to sphinx-contrib if someone wants to take over maintenance. |
|
Thanks @Holzhaus ! We appreciate your efforts here and honesty about availability. Given what you mention, maybe outlining some next steps could help. I feel a small group of us could effectively maintain the repository after transferring it to The following rough steps might be needed to reach this (please don't hesitate to correct / adjust - this is just a start!):
Thoughts? I think two or more maintainers for the @jykae @real-yfprojects @tjex (or others who may be watching the issue) - would you also be interested in being involved? |
@Holzhaus thank you so much for the work put into this project! 🙏
Ideally, we would move this repository directly to
If no other more suitable person steps up, I wouldn't be opposed. I can take care of the "management" aspects for issues, etc. and code reviews. But bear in mind that I'm not nearly as competent with Python as with C++/TypeScript/Haskell/... so don't expect any heroic contributions. However, I do use this at work and can probably divert a small bit of worktime to address critical issues or things like the pyro theme integration which my employer recognizes as benefitial. If nothing further comes up, I'll open an issue at |
@Holzhaus it seems like you are currently occupied with other projects and while that's perfectly fine, it would be unfortunate if this awesome sphinx extension would be strangled by it.
Therefore I propose to appoint one or two willing past contributors as maintainers and to move the repository to the sphinx-contrib organization. What is your opinion on this?
The text was updated successfully, but these errors were encountered: