Skip to content

Introduce markdown output for documentation purposes #2908

@waldekmastykarz

Description

@waldekmastykarz

Discussed in #2851

Originally posted by waldekmastykarz November 26, 2021
What do you think if we introduced in the CLI markdown output? It could be useful for generating documentation for the current configuration.

This idea is based on this thread on twitter: https://twitter.com/wictor/status/1463879429889867783?s=21 started by @wictorwilen

Introduce markdown output for documentation purposes. The Markdown output can be used with each command using --output md.

For get commands the output should be as follows:

Title/DisplayName/Name (Url/ID)

Property Value
Property1 Value1
Property2 Value2

For list commands the output should be as follows:

Title1/DisplayName1/Name1 (Url/ID1)

Property Value
Property1 Value1
Property2 Value2

Title2/DisplayName2/Name2 (Url/ID2)

Property Value
Property1 Value1
Property2 Value2
  • each section starts with a heading made of display name and an ID between brackets
  • to create the display name, the CLI will check if the object sent to output has a property named title, displayName or name (in this order). The value of the first property matched is used in the heading
  • in some cases properties can be named using Pascal case, like Title, DisplayName or Name, which we also need to take into account
  • to disambiguate between items with similar titles, the heading also contains either the url or or the id (again, take into account different casing variations, like Url, Id or ID)
  • the body of each section contains a table of key-value pairs for all properties including the properties used in the heading

Commands that already have an MD output, will keep the current output they already use.

Checklist:

Metadata

Metadata

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions