mkDocs -> bash docstrings to mdbook #521
Labels
No labels
dependencies
difficulty::high
difficulty::low
difficulty::medium
good first issue
help wanted
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
justin/makes#521
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
For the target use cases of
makes(in large orgas / monorepos) it would be extremely useful to provide a doc generator function that generatesmdbookdocs 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
mkRundeckfunction 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.mdnext tomain.nix.main.nix, for things like function argument documentation.To keep in mind:
./makesI 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.
This is going to be an absolute killer feature! 😄
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:@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!
Re: frontmatter
Related #554
It would be nice to add two jobs (linux/macos) for
/tests/scriptWithHelpinto.github/workflows/dev.ymlso we don't break it accidentally in the future