search

praiskup / argparse-manpage

Automatically build man-pages for your Python project
Apache License 2.0
40 stars 21 forks source link

Command line options help (documentation) differs from actually accepted command line input #110

Open damonlynch opened 4 months ago

damonlynch commented 4 months ago

There are errors regarding several options, e.g. --prog, --version, and --author-email.

Running the program's documentation help from the command line:

$argparse-manpage --help
usage: argparse-manpage [-h] (--module MODULE | --pyfile PYFILE) (--function FUNCTION | --object OBJECT) [--project-name PROJECT_NAME] [--prog PROG] [--version VERSION] [--description TEXT] [--author [AUTHOR]] [--url URL]
                        [--format {pretty,single-commands-section}] [--output OUTFILE] [--manual-section MANUAL_SECTION] [--manual-title MANUAL_TITLE] [--include FILE] [--manfile FILE]

Build manual page from Python's argparse.ArgumentParser object.

options:
  -h, --help            show this help message and exit
  --module MODULE       search the OBJECT/FUNCTION in MODULE
  --pyfile PYFILE       search the OBJECT/FUNCTION in FILE
  --function FUNCTION   call FUNCTION from MODULE/FILE to obtain ArgumentParser object
  --object OBJECT       obtain ArgumentParser OBJECT from FUNCTION (to get argparse object) from MODULE or FILE
  --project-name PROJECT_NAME
                        Name of the project the documented program is part of.
  --prog PROG           Substitutes %prog in ArgumentParser's usage.
  --version VERSION     Version of the program, will be visible in the manual page footer.
  --description TEXT    description of the program, used in the NAME section, after the leading 'name - ' part, see man (7) man-pages for more info
  --author [AUTHOR]     Author of the program. Can be specified multiple times.
  --url URL             Link to project's homepage
  --format {pretty,single-commands-section}
                        Format of the generated man page. Defaults to 'pretty'.
  --output OUTFILE      Output file. Defaults to stdout.
  --manual-section MANUAL_SECTION
                        Section of the manual, by default 1. See man (7) man-pages for more info about existing sections.
  --manual-title MANUAL_TITLE
                        The title of the manual, by default "Generated Python Manual". See man (7) man-pages for more instructions.
  --include FILE        File that contains extra material for the man page.
  --manfile FILE        File containing a complete man page.

Running the program from the command line:

$ argparse-manpage --function get_parser --pyfile parse.py --prog prog --version 0.0.1
usage: argparse-manpage [-h] (--module MODULE | --pyfile PYFILE) (--function FUNCTION | --object OBJECT) [--author AUTHOR] [--author-email AUTHOR_EMAIL] [--project-name NAME] [--url URL] [--output OUTFILE]
argparse-manpage: error: unrecognized arguments: --prog prog --version 0.0.1

This latter output shows that contrary to the program's help, the options --prog and --version are rejected. Also rejected would be --manual-section, --manual-title, --include, --format, and --manfile.

Furthermore, --author-email is valid, but not specified in the help.

praiskup commented 3 months ago

Thank you for the report. I can not reproduce the opt-parsing error:

$ ./argparse-manpage --object ap --pyfile ./argparse_manpage/cli.py --prog prog --version 0.0.1  > test.1
 !! running argparse-manpage from git, this is not supported PYTHON=python3!!

The --prog is though ignored, which seems to be a real bug.