Generate user documentation from bashly.yml about bashly

[DannyBen]

Glad you like it.

Can you give me an example of an expected markdown output?

[roquie]

Given that bashly supports nesting commands, the most convenient format for fully displaying documentation is to display it in a similar way as homebrew does in man (man brew). Example in the attachment. Markdown here will help with lists, titles, and highlighting options/flags/environment variables.

example.txt

Without strictly following the man rules, can just make it a similar format.

[DannyBen]

It shouldn't be too difficult to implement, the question is - should it be a part of bashly or not.

For the most part, the --help flag provides all the documentation you need. In the real world, you only need man pages or READMEs in case there is more information to share that is not available in the --help usage text.

If we implement this in bashly, the information will be identical, only formatted differently.

In addition, if we already generate a markdown documentation, someone else might want to generate man pages, or HTML documentation. So I am a little hesitant to create a "feature creep".

Let me think about it some more, and if you have thoughts on the above, feel free to share.

[roquie]

I see two ways.

First: implement this in bashly, because bashly.yaml an inseparable part of bashly and doc depends on it.

Second: make a plugin system for bashly, but I think for it is a large overhead. May be used a mixed solution: create an documentation abstraction in bashly for generate different formats. Anyone can add a HTML/PDF doc format.

[DannyBen]

I have already tried several approaches, but ultimately, ended up with a complex structure that is essentially generating the same thing as the usage text (--help) using different views.

Generating the script from the YAML today is a process that is done by using many small code snippets (see the views folder). This process needs to take into account many nuances, such as: Do we have subcommands or not? For each command, does it have flags? Default values? Required values? and many more.

[DannyBen]

I am closing this for now, the complexity of implementing it does not justify the benefits.

I am still open to be convinced otherwise.