Improved build script for doc repos (with change detection!)

Hi folks,

The one thing I’ve been struggling with when writing docs is the ./build.sh and ./preview.sh bits. One has to re-run ./build.sh each time one makes a change to see the new preview. This is far from ideal.

So I went looking for a way to emulate “watch for changes and rebuild as required” that tools like pelican and jekyll allow us to do and came up with a solution using inotifywait.

Now, one can run./builder.sh -w and it’ll watch the modules folder for changes and automatically rebuild when required.

I didn’t see a point of having different scripts for build and preview, so I’ve also subsumed ./build.sh and ./preview.sh into this script.

I’m testing it out with the NeuroFedora docs here, and it seems to work well. Could folks please test it out, and if it does work, can we please replace ./build.sh and ./preview.sh with this in all our repos to make it slightly easier for people to work locally on docs?

The file is here:

https://pagure.io/neuro-sig/documentation/blob/feat/improved-build-script/f/builder.sh

PR here in the NeuroFedora docs repo, so please feel free to drop comments there if you prefer:

https://pagure.io/neuro-sig/documentation/pull-request/23

$ ./builder.sh -h
./builder.sh: Build and preview Fedora antora based documentation

Usage: ./builder.sh [-awbpkh]

-a: start preview, start watcher and rebuilder
-w: start watcher and rebuilder
-b: rebuild
-p: start_preview
-k: stop_preview
-h: print this usage text and exit
5 Likes

Hey, that’s very, very welcome! At the moment I’m stuck with the release of a Server VM, but as soon as I write on docs again I’ll try it.

2 Likes

This is awesome, @ankursinha! I wish we had an easy way to roll it out to all of the repos (or distribute it independently of the repos)

2 Likes

How about adding it to a separate repository and integrating it using git submodules?

If it is just a single file, git submodules seem like overkill. I’d rather just see a comment added to the top of the script that indicates where the latest version can be downloaded from.

1 Like

One way, that would work for doc writers on Fedora at least, would be to create a fedora-docwriter package which is similar to the fedora-packager package. It’ll:

  • include this script (with a better name!)
  • pull in the various packages that are required: (python3, podman, inotify-tools)

That way, the script could live in one place instead of a copy living in each doc repo? We could leave the build.sh, preview.sh scripts in repos for the moment and deprecate them as we go by adding some text to them like this:

replaced by fedora-docwriter script. On Fedora, install `fedora-docwriter`. For other systems, you can get the script here: URL

Do we have/know any mac users who can please test the script to see how it works on macs?

I remember seeing a discussion on some doc-related issue on pagure about how best to distribute these scripts, but I can’t find it anymore. @bcotton any idea?
I think the idea of a dedicated RPM was mentioned, and I think it makes more sense now.

Edit: found it! Issue #5: How do we share template updates? - template - Pagure.io

2 Likes

Lots of changes to the script after Francois’s review folks, if you’d started using it already, please do use the latest version. I’ll leave the PR open for a bit for any more feedback. Then we can see if we want to move it to a different repo and make an rpm package etc.

1 Like

I will check out in the coming days if I find something on GitLab. It has several nice tools that go beyond the usual git functions (cherry-pick and such), maybe some of these tools can help/support us with the repos that have already moved to GitLab. Thanks @ankursinha !

1 Like