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:

  1. Documentation for the latest tagged stable release of the code in edge
  2. Documentation for the latest git HEAD version of the code
  3. 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.

git.sr.ht

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.

Notes from kernel hacking in Hare, part 1

One of the goals for the Hare programming language is to be able to write kernels, such as my Helios project. Kernels are complex beasts which exist in a somewhat unique problem space and have constraints that many userspace programs are not accustomed to. T…

via Drew DeVault's blog September 7, 2022

Linux machines that just work

In some sense, 2022 has been resembling the long-memed Year of the Linux Desktop. Although this sounds like some cult's prophetic rubbish, by looking at the success of the Linux desktop in very empirical terms an improvement of the last couple of year…

via TuxPhones - Linux phones, tablets and portable devices September 5, 2022

How to Build a Practical Household Bike Generator

We built a pedal-powered generator and controller, which is practical to use as an energy source and exercise machine in a household — and which you can integrate into a solar PV system. We provide detailed plans to build your own, using basic skills and …

via LOW←TECH MAGAZINE March 6, 2022

Generated by openring