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 two versions:
- Documentation for the latest tagged stable release of the code
- Documentation for the latest git HEAD version of the code
Having two versions allows us to document features as we add them to the git HEAD. 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:
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.
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
So locally, I have setup my remotes like this:
$ git remote -v devel firstname.lastname@example.org:~anjan/sxmo-docs-next (fetch) devel email@example.com:~anjan/sxmo-docs-next (push) origin firstname.lastname@example.org:~anjan/sxmo-docs (fetch) origin email@example.com:~anjan/sxmo-docs (push)
And my branches are setup like this:
$ git branch * develop master
I can add commits to the master branch and use
git push origin master to update the stable docs.
To update the development docs, I checkout the
develop branch and use
git push devel develop to update the develop docs.
I can always rebase the
develop branch on top of changes to the
Articles from blogs I follow around the netThese articles/blogs do not represent my own opinions or views.
I briefly mentioned postmarketOS in my Pinephone review two years ago, but after getting my Dutch SIM card set up in my Pinephone and having another go at using postmarketOS, I reckon they deserve special attention. Let’s first consider the kind of ecosystem…via Drew DeVault's blog November 26, 2021
Around the 17th century, the Dutch started reinforcing their dykes and harbours with sturdy mats the size of football pitches – hand-woven from thousands of twigs grown on nearby coppice plantations. These “fascine mattresses” were weighted with rocks and…via LOW←TECH MAGAZINE November 3, 2021
Generated by openring