makes
makes copied to clipboard
fluidattacks
mkDocs -> bash docstrings to `mdbook`
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...
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/
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
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.
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
@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!
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