Skip to content

Comments

Add workflow for building documentation#872

Draft
matsl wants to merge 2 commits intorswgnu:masterfrom
matsl:pr_doc_gen_github_workflow
Draft

Add workflow for building documentation#872
matsl wants to merge 2 commits intorswgnu:masterfrom
matsl:pr_doc_gen_github_workflow

Conversation

@matsl
Copy link
Collaborator

@matsl matsl commented Feb 24, 2026

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.

* .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.
@matsl matsl marked this pull request as draft February 24, 2026 22:48
@matsl matsl requested a review from rswgnu February 24, 2026 22:56
Copy link
Owner

@rswgnu rswgnu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@matsl
Copy link
Collaborator Author

matsl commented Feb 25, 2026

Don't have much to say about this if it works.

You can look here for how it looks https://github.com/rswgnu/hyperbole/actions/runs/22373193416/job/64757138844?pr=872

Make sure the foreach works with non-gnu make.

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.

And I don't yet understand the change in handling the .html file but generally looks good.

The target is split into two to make the dependencies more clear.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants