mkDocs -> bash docstrings to mdbook #521

Open
opened 2021-09-10 03:17:51 +02:00 by blaggacao · 8 comments
blaggacao commented 2021-09-10 03:17:51 +02:00 (Migrated from github.com)

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...

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 commented 2021-09-10 07:42:37 +02:00 (Migrated from github.com)

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/

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 commented 2021-09-16 07:35:20 +02:00 (Migrated from github.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
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 commented 2021-09-18 21:22:50 +02:00 (Migrated from github.com)

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.

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 commented 2021-09-18 23:36:20 +02:00 (Migrated from github.com)

This is going to be an absolute killer feature! 😄

This is going to be an absolute killer feature! :smile:
kamadorueda commented 2021-09-19 01:20:41 +02:00 (Migrated from github.com)

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.

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

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:

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

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

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 commented 2021-09-19 02:35:26 +02:00 (Migrated from github.com)

@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!

@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 commented 2021-09-19 14:26:44 +02:00 (Migrated from github.com)

Re: frontmatter

Related #554

Re: frontmatter Related #554
kamadorueda commented 2021-09-20 18:15:29 +02:00 (Migrated from github.com)

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

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
This discussion has been locked. Commenting is limited to contributors.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
justin/makes#521
No description provided.