Generate documentation based on your taskfile

[kk-rishang]

We have option for displaying summary, also we configure input variables. I we use multiple task modules and sharing between teams, document generation tool can really helpout to have better visibility on how to use the task module one created.

I created my own python code to generate docs: https://github.com/Rishang/task-templates/blob/main/generate_docs.py

And here is how the docs look: https://github.com/Rishang/task-templates/blob/main/docs/_aws.md

[pd93]

I've wanted to overhaul the task formatter for a while so that you can do something like:

task --list --format=json

A nice way to do this might be to support:

task --list --format=markdown

Since most docs servers support some flavour of markdown, this would allow us to support them in a generic way. We could even do this ourselves to document our project Taskfile using our Docusaurus site.

[trulede]

You can see what I did to generate documentation, which is consumed by a VS Code extension, for autocomplete operation.
#1916 (comment)

Note that the task schema is not (currently) sufficient for the task of documenting a task completely, so I had to put it in a metadata file, along with other things that did not fit in the schema.

We would/will use that to also generate MD doc, but @pd93 please be aware, generated Markdown still needs to work within a documentation system (i.e. Hugo) and existing documentation styles, so a templating mechanism would probably be better.

Perhaps, one way to do this would be to simply walk the AST and apply a user provided go template file. That way its possible to get the doc generated according to the needs of the documentation system we are targeting.

[trulede]

#2261 and #2091 brings up a similar topic, custom output for list command ... I did something with the --json option, but it's a bit clunky.

@pd93 might it be possible to do this using the text/template go stdlib, then the output can be user defined. Something like this, based on the json object created by the --json flag, but extended to include vars too:

task --list=template.txt

template.txt

## {{.name}}
{{.desc}}

### Aliases
{{range .aliases}}
    - {{.}}
{{end}}

### Summary
{{.summary}}

### Vars
{{range .vars}}
    - {{.name}} = {{.default}} 
{{end}}

Having access to a metadata object (#1916) would further support the use case.