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鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

feature: Generate manpage from CLI #25

Open
pawamoy opened this issue May 8, 2024 · 0 comments
Open

feature: Generate manpage from CLI #25

pawamoy opened this issue May 8, 2024 · 0 comments

Comments

@pawamoy
Copy link
Owner

pawamoy commented May 8, 2024

The build backend configuration in pyproject.toml is already setup for including manpage that pipx can install in a specific folder. Users who add this folder to their MANPATH can then type man your-cli to get some help 馃憤

I had spent some time integrating mkdocs-manpage into this template, but there were two things I disliked about this approach:

  • Docs had to be built before the distributions, because the manpage are generated when building the docs. That reverses our current order of operations (publish package && deploy docs), and also creates a dependency between docs-building and dist-building. Not great
  • The manpage generated from the docs is... big. And not well crafted. We can select pages explicitely, but even then, the contents of these pages is made to be read in a browser more than in a terminal. Pandoc does a great job at converting HTML to Groff, but it can't do magic for the content itself.

I'd really prefer a specially crafted manpage that reflects the CLI only, just like regular man pages for GNU/Linux tools. The rest of the documentation can stay online, as HTML.

I believe it's easy enough to write a script that generates Groff from an argparse/Cappa CLI, like click-man does. This script could either live in generated project, or I could create a new package. If the latter, this could be listed in Cappa's docs 馃槈

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant