Sourcehut multiple documentation versions
Published 2021-10-29 on Anjan's Homepage
When using man.sr.ht for Sxmo’s documentation we wanted to have three versions:
- Documentation for the latest tagged stable release of the code in edge
- Documentation for the latest git HEAD version of the code
- Documentation for the latest tagged stable release in postmarketOS stable
Having three versions allows us to document features as we add them to the git HEAD or postmarketOS edge. Additionally, we want to serve up an HTML version of both versions so that users of the git HEAD can read how the new features work and users of the stable releases don’t get information about features that don’t exist.
Ideally, man.sr.ht would have a drop down menu to select different git branches/tags of the git repo you feed it. I opened an issue about this:
https://todo.sr.ht/~sircmpwn/man.sr.ht/53
For now, I had to find a workaround.
So I opened two man.sr.ht wikis and two git repos: sxmo-docs and sxmo-docs-next.
In sourcehut, each man.sr.ht wiki must point to a branch.
The sxmo-docs wiki points to the master
branch on the sxmo-docs git repo and the sxmo-docs-next wiki points to the develop
branch on the sxmo-docs-next git repo.
Here are the webpages for the man.sr.ht wikis and git.sr.ht git repos.
man.sr.ht
git.sr.ht
- https://git.sr.ht/~anjan/sxmo-docs
- https://git.sr.ht/~anjan/sxmo-docs-next
- https://git.sr.ht/~anjan/sxmo-docs-stable
You might be wondering why I did this.
Often, I will fix the documentation in the stable version of the wiki (sxmo-docs) but since the git HEAD version of the code has that change too, I want to be able to rebase sxmo-docs-next on top of my commits to sxmo-docs.
Clearly this is a case where I would use git rebase.
Setting up the wiki and git repos like this, I am able to have one local repo on my machine with two branches and update both wikis with git-rebase
git-push
.
So locally, I have setup my remotes like this:
$ git remote -v devel git@git.sr.ht:~anjan/sxmo-docs-next (fetch) devel git@git.sr.ht:~anjan/sxmo-docs-next (push) origin git@git.sr.ht:~anjan/sxmo-docs (fetch) origin git@git.sr.ht:~anjan/sxmo-docs (push) stable git@git.sr.ht:~anjan/sxmo-docs-stable (fetch) stable git@git.sr.ht:~anjan/sxmo-docs-stable (push)
And my branches are setup like this:
$ git branch
* develop
master
stable
I can add commits to the master branch and use git push origin master
to update the edge docs.
To update the development docs, I checkout the develop
branch and use git push develop develop
to update the develop docs.
To update the docs in postmarketOS stable, I checkout the stable
branch and use git push stable stable
to update the postmarketOS stable docs.
I can always rebase the develop
branch on top of changes to the master
branch.
Have a comment on one of my posts? Start a discussion in my public inbox by sending an email to ~anjan/public-inbox@lists.sr.ht [mailing list etiquette]
Articles from blogs I follow around the net
These articles/blogs do not represent my own opinions or views.Todo.txt-more: Efficiently managing your todo list and your time
Todo.txt More: Efficiently managing your todo list and your time Introduction I tend to get fairly enthusiastic when it comes to lists, even more so when there's a chance to optimise my productivity. The end of the year is a time for looking backward an…
via Proycon's website December 31, 2022The PineTab2 is a new, faster Linux tablet - and it's not alone
In their December update, Pine64 announced the PineTab2, which is the successor to their PineTab from 2018. As a major change, the PineTab2 upgrades the slow A53-based A64 SoC with an A55-based Rockchip RK3566, the same chip that was used for the Quartz64…
via TuxPhones - Linux phones, tablets and portable devices December 19, 2022I shall toil at a reduced volume
Over the last nine years I have written 300,000 words for this blog on the topics which are important to me. I am not certain that I have much left to say. I can keep revisiting these topics for years, each time adding a couple more years of wisdom and impro…
via Drew DeVault's blog December 1, 2022Generated by openring