You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 😉
Boost priority
Boost priority in our backlog through Polar.sh. Higher pledge, higher priority.
Minimum pledge by user/organization is $5, minimum amount for boost is $30.
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 typeman 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:
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 😉
Boost priority
The text was updated successfully, but these errors were encountered: