feat: add support for generating modular docs

[pmuir]

Description

Add support for converting the docs produced by the Command Line Interface docs generator to the "modular docs" format and pushing them to the modular-docs branch on very push to main. This allows other systems to then pick them up as needed.

Verification Steps

1. Run make docs/generate-modular-docs
2. Inspect the output in dist
3. On merging the PR, the branch modular-docs should be populated with the contents of the dist dir

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• Documentation added for the feature
• CI and all relevant tests are passing
• Code Review completed
• Verified independently by reviewer

[wtrocki]

👁️

[wtrocki]

@pmuir Any example of another system to validate file structure.
Got structure working locally, tried job on my fork.

All seems to be working. The only trick is to prevent things from changing in future as any structure change will need developer to adjust scripts.

To fully understand it - other systems will be syncing this branch itself - means that they will be responsible for versioning etc.?

[wtrocki]

FYI Generated files have
ifdef::env-github,env-browser[:relfilesuffix: .adoc] which is upstream fix - not an issue but not needed for downstream

Checked previews and github links - all works!

[pmuir]

@pmuir Any example of another system to validate file structure.
Got structure working locally, tried job on my fork.

For example https://github.com/bf2fc6cc711aee1a0c2a/guides/tree/modular-docs

All seems to be working. The only trick is to prevent things from changing in future as any structure change will need developer to adjust scripts.

Yes, though given the docs are all generated, that probably isn't a major issue.

To fully understand it - other systems will be syncing this branch itself - means that they will be responsible for versioning etc.?

Right.

[wtrocki]

Good to merge

[bhardesty]

I verified that this works for me. I did have some scripting to build the assembly from the CLI, but this works just as well. The only issue would be it would be slightly more complicated if we ever wanted to change something like the assembly intro text.

[pmuir]

FYI Generated files have
ifdef::env-github,env-browser[:relfilesuffix: .adoc] which is upstream fix - not an issue but not needed for downstream

Checked previews and github links - all works!

This is the recommended way to handle links that work on both github and in other systems.