I‘m looking for a way to add unit tests to my documentation. I generate my docs website from asciidoc using antora. Works perfectly fine. Now I am looking for a way to unit test my docs (asciidoc files as well). But this is not my question right now.
What I want right now is a way to test the filesystem structure of my docs. I have several repos with similar base setup and basic docs. The details differ but e.g. I want to ensure every docs have their main docs in PROJECT/docs/modules/ROOT and the navigation file is named nav.adoc in every module etc.
Basically I want the same docs structure for every project.
So I wonder if there is a way to test the filesystem (foldernames, Filenames). Ultimately these tests should be part of my gitlab ci pipeline.
Can archunit help with that? I’d consider it if there is no better way, but since archunit targets java projects it seems like overkill for my uaecase.
It is important to remember that Antora can gather content from multiple repos. When Antora gathers content, that content is held in a virtual filesystem until the transformation to HTML is complete. That means that wherever you run Antora, the filesystem structure of the repos cannot be directly interrogated unless it happens to be local (you're using "author" mode, or you have an up-to-date checkout of the repo(s) locally).
It is possible to write an extension for Antora (in JavaScript, since Antora is a Node.js application) to investigate the virtual filesystem and complain about any structural problems found.
Outside of Antora, you'd basically be writing a repo-specific test. That test could be invoked any way you like, say by running a test script when
makeis run. Or, you might add a git commit hook to your repo that prevents commits when the appropriate file structure does not exist.The TL;DR answer is "yes, this can be done". However, it requires some implementation effort to achieve.