Feat: Added tabular markdown writer

[tarampampam]

What type of PR is this?

• feature

What this PR does / why we need it:

This PR allows to render of CLI usage docs in tabular markdown (App.ToTabularMarkdown("app_name")), with is pretty cool to use in the readme files.

Tip: You can watch the "tabular markdown" file by the following link.

In addition, I've added a function named ToTabularToFileBetweenTags which provides an easy way to update the CLI usage help in the readme files. Users now only need to create a file (update_readme.go):

//go:build ignore
// +build ignore

package main

import "example"

func main() {
  var app = example.NewApp() // <-- your app here, typeof *cli.App

  if err := app.ToTabularToFileBetweenTags("app", "../README.md"); err != nil {
    panic(err)
  }
}

Add the following comment somewhere in the app code:

//go:generate go run update_readme.go

Plus put the following tags (which can be configured, of course) into the readme file:

<!--GENERATED:CLI_DOCS-->
<!--/GENERATED:CLI_DOCS-->

And voila! After running go generate ./... the readme file will contain fresh CLI documentation, which will never become outdated because it is not handy-crafted.

Co-authored with @jetexe

Which issue(s) this PR fixes:

Fixes #1721

Testing

I wrote all required unit tests.

Release Notes

Added markdown tabular writer, which can be used to automatically generate a CLI
usage section in the readme file using the `go generate` tool.

[tarampampam]

Friendly ping @dearchap @urfave

[tarampampam]

Friendly ping @meatballhat @dearchap @asahasrabuddhe @coilysiren

[dearchap]

@tarampampam To confess I am not a markdown expert so I cannot make some sense of the changes. It is going to take me some time unless one of the other @urfave/cli maintainers want to go ahead and comment

[abitrolly]

Why it is called tabular?

[dearchap]

@tarampampam We would definitely like it to be merged since the display looks awesome. Can you give me a couple of days to review ? Thanks for your patience.

[tarampampam]

I have made all changes, requested by you. Hope you like the code now :)

[tarampampam]

Thank you so much, guys!

[tarampampam]

May I ask - how soon do you plan to release those changes?

[abitrolly]

Usually there is a release every two weeks - https://github.com/urfave/cli/releases

[skelouse]

Usually there is a release every two weeks - https://github.com/urfave/cli/releases

@paulmakepeace

You can go get urfave/cli@main if you want to use it now.

[tarampampam]

Usually there is a release every two weeks - https://github.com/urfave/cli/releases

@abitrolly @dearchap It's been over three weeks and still no release :(

[abitrolly]

I don't have money and I'm in de-pression to follow schedules. :D

Let me try https://github.com/urfave/cli/blob/main/docs/RELEASING.md to see if I have enough privileges (and battery life) to do this.

[abitrolly]

Okay. The problem is that the PR is in the main, which is code for unreleased v3. #833

I am now sure how version tracking works. Like what revision will you get, if you do go get github.com/urfave/cli/v3@latest, and how go knows what is the v3 commit, when there is no v3 branch and no v3 tag in this repo.

That's all I could do for now. Need some clarifications from @meatballhat (#833 (comment)).

[tarampampam]

Maybe you could squash the commits from acbbbf2 to b857483 (in the main branch) and cherrypick the result commit to the v2-maint branch?

I have no idea why my commits flood was rebased to the main branch... I was hoping they would be squashed by default. Sorry for that

[jetexe]

and how go knows what is the v3 commit, when there is no v3 branch and no v3 tag in this repo.

There is two v3 tags now: v3.0.0-alpha and v3.0.0-alpha2

[meatballhat]

@abitrolly sorry for my delay! I'm happy to tag a v3.0.0-alpha3 👍🏼

[meatballhat]

@abitrolly Done! Try go get github.com/urfave/cli/v3@latest or similar now?

[abitrolly]

@tarampampam ^^^

@jetexe so Go is able to figure out that v3@latest is v3.0.0-alpha3, I see.