Automatic docs update makes the git tree ugly and harder to read. Suggestions?

[Mark-LaCroix]

Looking for some help or suggestions on this. First, some background:

The documentation for this project is written directly in the code comments of each file, formatted for a tool called LDoc which generates HTML pages from those code comments. It is very important to me that the docs are up-to-date, accurate, and easy to understand, and this workflow has proven an efficient and effective way to maintain this pillar of the project.

Originally, I would run LDoc locally on my machine in order to generate the HTML pages, but I would often forget to to it before pushing a change, which meant the doc changes would need to be pushed separately (sometimes not until much later when I noticed I hadn't yet done it), or I'd be on a machine which hadn't had LDoc set up on and couldn't do it at all (installing and configuring LDoc and its web of dependencies has been a hassle and extremely error-prone, at least for me). This meant that the human-readable docs on GitHub Pages would sometimes be out of date with the documentation as written.

Thankfully, I've since learned that LDoc can be configured as a GitHub Action, which means I can now just have a VM on GitHub's servers spin up and run LDoc on the repo for me on every push to the main branch, instead of needing to install it locally myself. The other benefit of this is that if LDoc can't make sense of the latest changes because the documentation in the code comments themselves weren't updated, I'll get a push notification from GitHub.

So, all great! Except...

Because the HTML files are themselves part of the repo (so you can view them offline but mainly so they can be a source for GitHub Pages), a new commit needs to be pushed to main every time. This means that every other commit on the main trunk of the git tree is "(Documentation updates)."

This is fine, more or less, but it bothers me because it makes it harder to read the git tree if you want to examine the project's history or review recent changes. It also makes it look like there's twice as much activity on the project, which is confusing.

One way to fix this is: once the docs commit is pushed, to have another GitHub Action squash that new commit with the previous one, so it's one commit. This will work on origin, and for users whose local copy of the repo would never be checked out on the "pre-doc-update" commit, but I worry it will cause problems on my (or any future maintainers who can push to main) development machines, since that local repo be out of sync. Maybe this wouldn't be so hard to deal with, but I've had trouble in the past on other projects when commits are "amended" like that.

Perhaps this is all invisible to people who only use git via command line, but I use the app Fork to manage my git projects (and GitHub Desktop to generate PR branches locally for review), and it makes the project feel... less "tidy" than my other big projects.

But before I start mucking around on this, I'd love some suggestions/advice.