Open christianaaronschroeder opened 3 weeks ago
That's a great point Christian, and I'd like to improve that. But I'm not sure how to do it in a sane way without too much manual labour on every release. Maybe you have some ideas?
I'd like it to be just like on https://pydata-sphinx-theme.readthedocs.io/en/stable/, with a version number with (latest) as default. And a dev
option with the main branch docs. But since they use readthedocs I can't just copy their Github Actions settings.
Currently we have this Github Actions workflow for docs: https://github.com/python-visualization/folium/blob/main/.github/workflows/deploy-docs.yml. It does two things:
main
, push the docs to the existing latest
folder on the gh-pages
branch.gh-pages
branch.Then on release we have to manually update the switcher.json
file in our repo.
Note that our gh-pages
branch has a file index.html
which redirects to the latest
folder, which is why that one is used by default.
I'd like it to be so that:
main
, update the dev
folder on the gh-pages
branch.switcher.json
file in our repo (i.e. make a commit)gh-pages
branch.Updating the switcher.json
file automatically is something I'm not sure how we can do that sensibly. Help is welcome!
I stumbled upon this for the same reason as @christianaaronschroeder. At that note, when is the next release planned? :pleading_face:
However, I took a stab at your request @Conengmo . Find it here (direct link to changes).
I didn't see a minimal way to achieve the requested functionality without introducing some potentially hard to maintain jq
-fu, so, I created a small script that does the bump in switcher.json
(which is hopefully easier to read).
The changes are intended to get pushed via stefanzweifel/git-auto-commit-action, but that won't work in the current form as main is a protected branch. There is a way of bypassing the protection by using a PAT created for specific actors allowed to override protection, but that feels unclean. So, maybe it should instead open a PR automatically and request a review from specific people? That would also allow some manual intervention (some more info on this).
Let me know what you think. Happy to push this further if it makes any sense. :blush:
This is great Marius! Really happy with what you made so far. Making a Python script to update the switcher json file makes a lot of sense. It's easy to read. And your suggestion to open a PR automatically with the switcher change seems perfect to me. Hope you have the time to make a PR with this!
Happy to help. Also, thanks a lot for the great work on the project! It helped me a lot. :hugs:
I will try to finish the PR tonight (I should have some time).
I will probably stick with automatically creating a PR and pinging for reviews. It's not fully automated that way, but less of a security concern. Happy about comments on this though. :blush:
Sorry for sitting on this for longer than planned. :grimacing:
I don't think there is an obvious solution to this, so, I want to list some options first as the decision should be made by the maintainers of the repository.
I played around with two options mainly and have others in mind (happy to look into them). I'll list them below:
stefanzweifel/git-auto-commit-action@v5
in combination with a PAT (Personal Access Token, fine-grained) to push the changes directly to main
from the workflow.
PAT
).main
.
Let me know what you think. Happy to keep pushing this further.
The drafts of the first two options live here (option 1) and here (option 2). I played with them for a while in a sandbox repository here.
cc @Conengmo
This could be me misunderstanding what is meant by "latest" but I've noticed a few times that there is a feature that the docs imply is available in the "latest" release but is not actually available yet, rather it will be available in the next release.
E.g. A new plugin, TreeLayerControl, is now listed as part of the "latest" version in the docs. However, it was only merged back in April (https://github.com/python-visualization/folium/pull/1895) and is not actually available in the "latest" release, 0.16.0.