The documentation folder structure could be simplified, as currently ASCIIDoc components reside within manual/, while the published documentation resides within doc/.
This is probably to work around the fact that github.io (the documentation hosting mechanism) will only publish pages from the project root, or a folder called doc/.
Proposed changes
I suggest that we modify the documentation publication process, so that -
The documentation is published out of the project root on a separate branch (which we'll call site-publish).
Documentation sources reside within doc/.
A branch called site-staging is created at every pull request to enable review.
When a pull request is approved, site-staging is promoted to site-publish via Github actions (or CircleCI if preferred).
Summary
The documentation folder structure could be simplified, as currently ASCIIDoc components reside within
manual/, while the published documentation resides withindoc/.This is probably to work around the fact that github.io (the documentation hosting mechanism) will only publish pages from the project root, or a folder called
doc/.Proposed changes
I suggest that we modify the documentation publication process, so that -
doc/.site-stagingis created at every pull request to enable review.site-stagingis promoted tosite-publishvia Github actions (or CircleCI if preferred).