Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feat: Added tabular markdown writer #1722

Merged
merged 28 commits into from
May 1, 2023
Merged

Feat: Added tabular markdown writer #1722

merged 28 commits into from
May 1, 2023

Conversation

tarampampam
Copy link
Contributor

@tarampampam tarampampam commented Apr 14, 2023

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.

…ation

✅ test(docs_test.go): add tests for generating tabular markdown documentation

✨ feat(template.go): add MarkdownTabularDocTemplate to generate a markdown table for command flags and environment variables
🐛 fix(fish_test.go): add EXAMPLE_VARIABLE_NAME to another-flag's EnvVars
✨ feat(template.go): add support for multiline UsageText in MarkdownTabularDocTemplate
…AppPath function

✨ feat(docs.go): add ToTabularToFileBetweenTags function to generate tabular markdown documentation and update file between tags
🔨 refactor(docs_test.go): update tests to use ToTabularMarkdown with appPath parameter instead of TabularOption
✅ test(docs_test.go): add tests for ToTabularToFileBetweenTags function
…ace function call to ignore windows line endings
🔥 refactor(docs_test.go): comment out unused windows line endings replacement
🐛 fix(docs_test.go): fix expected content type to byte array
🔥 refactor(docs_test.go): comment out unused code
✨ feat(docs_test.go): add normalizeNewlines function to normalize windows and mac newlines into unix newlines
@tarampampam tarampampam marked this pull request as ready for review April 14, 2023 15:37
@tarampampam tarampampam requested a review from a team as a code owner April 14, 2023 15:37
@tarampampam
Copy link
Contributor Author

Friendly ping @dearchap @urfave

@tarampampam
Copy link
Contributor Author

Friendly ping @meatballhat @dearchap @asahasrabuddhe @coilysiren

@dearchap
Copy link
Contributor

@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
Copy link
Contributor

Why it is called tabular?

@dearchap
Copy link
Contributor

@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.

docs_test.go Outdated Show resolved Hide resolved
docs.go Show resolved Hide resolved
docs.go Outdated Show resolved Hide resolved
dearchap
dearchap previously approved these changes Apr 30, 2023
…rMarkdown and remove TestToTabularMarkdownWithEmptyAppPath

✨ feat(docs_test.go): add subtests to TestToTabularMarkdown to test different scenarios
🔥 chore(docs_test.go): remove unused variable and restore MarkdownTabularDocTemplate after test
@tarampampam
Copy link
Contributor Author

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

@tarampampam tarampampam requested a review from dearchap May 1, 2023 06:43
@meatballhat meatballhat added area/v3 relates to / is being considered for v3 kind/feature describes a code enhancement / feature request labels May 1, 2023
@dearchap dearchap merged commit acbbbf2 into urfave:main May 1, 2023
@tarampampam
Copy link
Contributor Author

Thank you so much, guys!

@tarampampam
Copy link
Contributor Author

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

@abitrolly
Copy link
Contributor

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

@skelouse
Copy link
Contributor

skelouse commented May 3, 2023

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
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor

jetexe commented May 26, 2023

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
Copy link
Member

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

@meatballhat
Copy link
Member

meatballhat commented May 27, 2023

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

@abitrolly
Copy link
Contributor

@tarampampam ^^^

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/v3 relates to / is being considered for v3 kind/feature describes a code enhancement / feature request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Better markdown docs generation
6 participants