Add workflow for building documentation#872
Conversation
* .github/workflows/docs.yml: New workflow
* Makefile (TEXICMD): Fail build on errors
(doc-clean): Use make foreach for removing doc build artifacts. (Avoid
bash brace expansion.) Remove README.md.html and README.toc.md.
rswgnu
left a comment
There was a problem hiding this comment.
Don't have much to say about this if it works. Make sure the foreach works with non-gnu make. And I don't yet understand the change in handling the .html file but generally looks good.
You can look here for how it looks https://github.com/rswgnu/hyperbole/actions/runs/22373193416/job/64757138844?pr=872
I'm afraid many gnu-make specifics have already crept in over the years. We both use Linux as development platform and use Linux images for CI/CD making this go under our radar. So changing this to work with non-gnu (i.e. POSIX) make will not fix that. It is of course trivial to expand the foreach in place but I thought that would look clumsy. gnu-make is possible to install on other systems so I think we should just keep using gnu-make specifics for making our daily work simpler.
The target is split into two to make the dependencies more clear. |
What
Add workflow for building documentation.
.github/workflows/docs.yml: New workflow
Makefile (TEXICMD): Fail build on errors.
(doc-clean): Use make foreach for removing doc build artifacts. (Avoid
bash brace expansion.) Remove README.md.html and README.toc.md.
Why
We need to check that building the docs works. This is a first step in
that direction.
Note
The "Build Docs" check will only trigger for updates below "man" folder and changes to markdown files. Stricter error checking has been applied for texi2any that will fail for a single error. (Default is 100 I think.) No other error checking is performed.
We could add check for Underfull and Overfull messages but I know to little about that now. I suggest we inspect the output in the Build Docs step for now.
An extra line has been inserted in README.md to trigger the build. This needs to be removed before we can merge this PR. Hence it is set as draft for now until we have it in a shape we want.