Investigate auto generating parts of docs

[devlead]

Currently the CLI usage is out of sync with the latest release i.e. experimental is there, bootstrap isn't and so on.

Got me thinking this should be able to be codegened, putting this in an issue for future discussion.

Did a quick PoC just parsing the help command output

Usage: Cake.exe [script] [--verbosity=value]
                [--showdescription] [--dryrun] [..]

Example: Cake.exe
Example: Cake.exe build.cake --verbosity=quiet
Example: Cake.exe build.cake --showdescription

Options:
    --verbosity=value    Specifies the amount of information to be displayed.
                         (Quiet, Minimal, Normal, Verbose, Diagnostic)
    --debug              Performs a debug.
    --showdescription    Shows description about tasks.
    --dryrun             Performs a dry run.
    --exclusive          Execute a single task without any dependencies.
    --bootstrap          Download/install modules defined by #module directives
    --version            Displays version information.
    --help               Displays usage information.

result is

Code for that is avail here, it's just a rough 5 minute PoC.

Ideally we should have better meta data i.e. if cake could report as xml, json etc. but wanted to test something end to end, basic idea is

• Have a main manually created document
• Where parts of the document is automatically generated

In the poc this is achieved using the WYAM include module and ^ preprocessor example:

`^"../../../generatedinput/cake-usage.md"

[pascalberger]

While in the meantime CLI would support exporting of its parameters, we additionally document version in which a parameter was introduced, which means that we can't use the CLI output for generating documentation.

[patriksvensson]

I think we can scrap versioning once 1.0 has been released.

[pascalberger]

I think we can scrap versioning once 1.0 has been released.

Don't necessarily agree. Version column was just introduced a few weeks ago with a near 1.0 release. Also after 1.0 it's still possible that we add CLI paramaters.

IMHO it would be nice if we have the option to annotate the parameters with a version attribute, which we then can use for documentation.

[patriksvensson]

Personally I think it's overkill. Especially since we have the option to autodocument arguments with Spectre.Cli.

[devlead]

I think it's really useful when debugging i.e. if a build on CI fails it could be because it's running a old version, each version has its behavior, having the point in time when behavior changed can be really helpful. Could be that a breaking change occurred in between latest and used version, then you get a feeling for how new you can go quickly, before refactoring to latest.