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

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
Assignees
Labels
feature New feature or request fund Issue priority can be boosted

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 😉

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.
  • View all issues with pledges.
  • We receive the funds once the issue is completed and confirmed by you.
  • Features with the insiders label are released to sponsors first, and tied to a funding goal.
Fund with Polar
@pawamoy pawamoy added feature New feature or request fund Issue priority can be boosted labels Oct 25, 2024
@pawamoy pawamoy mentioned this issue Oct 25, 2024
@pawamoy pawamoy self-assigned this Jan 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feature New feature or request fund Issue priority can be boosted
Projects
None yet
Development

No branches or pull requests

1 participant