mkDocs -> bash docstrings to `mdbook`

[blaggacao]

For the target use cases of makes (in large orgas / monorepos) it would be extremely useful to provide a doc generator function that generates mdbook docs from code comments.

Maybe some of the existing tooling such as https://github.com/nix-community/nixdoc/pull/25 can be hijacked.

To achieve the necessary standardization and reap it's benefits, I guess, it makes sense to think this through right from the start...

[blaggacao]

A natural extension of this Idea would be a mkRundeck function that is like a manual & serialized version of a pipleline intertwined in a markdown document with apropriate emergency response instructions.

See also: https://www.rundeck.com/

[blaggacao]

After my first half-way-through job implementation, I'm thinking that probably the best way to document a job is by just adding a README.md next to main.nix.

• It will be nicely displayed in github
• We could detect that and append it as a docs-md string to the job package
• We could then collect those outputs and build a mdbook out of it.
• This approach can still be combined with parsing nix code comments in any main.nix, for things like function argument documentation.

To keep in mind:

• relative paths should be kept working between github and mdbook, that is the mdbook structure must mimick the structure within ./makes

[blaggacao]

I think I'll be working on this one next, since I want to set that standard & benchmark for our repo's evolution right from the start for myself & others.

[blaggacao]

This is going to be an absolute killer feature! :smile:

[kamadorueda]

The readme to the side of main.nix sounds good, however readme's are free-form which means people can write in any order and not adhere to some standards

if we want to have some order (a schema), we can use YAML.

• https://gitlab.com/fluidattacks/product/-/blob/master/makes/foss/modules/makes/criteria/src/vulnerabilities/data.yaml

and a schema for validating it with tools as https://ajv.js.org/ (we currently have it builtin into the framework):

• https://gitlab.com/fluidattacks/product/-/blob/master/makes/foss/modules/makes/criteria/src/vulnerabilities/schema.json

Nix can process the YAML and render markdowns that then are feed into a markdown-to-html framework like https://docusaurus.io/ which make things look pretty nice:

• https://docs.fluidattacks.com/criteria/vulnerabilities/

and since everything has a schema one can do further programmatic processing to generate inverse indexes, etc:

• https://docs.fluidattacks.com/criteria/compliance/012

this is the source code of the generator, it uses a lot makeTemplate:

• https://gitlab.com/fluidattacks/product/-/tree/master/makes/foss/units/docs/generate/criteria

[blaggacao]

@kamadorueda You make me have an idea!

Freeform, I guess is actually an advantage. Especially for things like runbooks, etc., which require some extensive context and explanation.

However, we can bake a structured short-help into the front matter! 🚀

Best of both worlds!

[blaggacao]

Re: frontmatter

Related #554

[kamadorueda]

It would be nice to add two jobs (linux/macos) for /tests/scriptWithHelp into .github/workflows/dev.yml so we don't break it accidentally in the future