Package: argparse-manpage
ArgumentParser instance → manual pageAvoid documenting your Python script arguments on two places!  This is typically
done in anargparse.ArgumentParserhelp configuration (help=,description=, etc.), and also in a manually crafted manual page.The good thing about anArgumentParserobjects is that it actually provides
a traversable "tree-like" structure, with all the necessary info needed toautomatically generatedocumentation, for example in agrofftypesetting
system (manual pages).  And this is where this project can help.There are two supported ways to generate the manual, either script it using the
installed commandargparse-manpage, or viasetup.py buildautomation (with a
slight bonus of automatic manual page installation withsetup.py install).What is need?Most of the (meta)data is stored in theArgumentParserobject, thereforeargparse-manpageneeds to know its location—it can be either the object
itself, or a method to call to get the object [^1].On top of this, several manual page fields (likeauthororprojectname)
need to be specified, either on command-line or viasetup.pymetadata.Command-line usageSee the following example:$ argparse-manpage --pyfile ./pythonfile.py --function get_parser \
                   --author "John --author-email doe@example.com" \
                   --project-name myproject --url https://pagure.io/myproject \
> cool-manpage.1This (a) processes the./pythonfile.py, (b) calls theget_parserinside to
obtain theArgumentParserinstance, (c) transforms it into a manual page and
(d) stores it into thecool-manpage.1file.Alternatively those options above can be combined withoption--module mymodule.main, to load a Python modulemymodule.mainfromPYTHONPATH, or--object parser_object_nameif theparser_object_nameis a global
variable.Use with pyproject.tomlFirst, you need to declare inpyproject.tomlthat argparse-manpage is needed
at build-time and use the setuptools.builds_meta` backend:[build-system]requires=["argparse-manpage[setuptools]"]build-backend="setuptools.build_meta"Alternatively, you can place thebuild_manpages(sub)directory from this
project somewhere ontoPYTHONPATHso you can use it at build time.  For
example:gitsubmoduleadd--namebuild_manpageshttps://github.com/praiskup/build_manpages
gitsubmoduleupdate--initThen inpyproject.toml(re)definecmdclasscommands:[tool.setuptools.cmdclass]build_py="build_manpages.build_py"install="build_manpages.install"build_manpages="build_manpages.build_manpages"And specify the list of built manual pages:[tool.build_manpages]manpages=["man/foo.1:object=parser:pyfile=bin/foo.py","man/bar.1:function=get_parser:pyfile=bin/bar","man/baz.1:function=get_parser:pyfile=bin/bar:prog=baz",]Use with setup.pyIn yoursetup.pyuse pattern like:[...]frombuild_manpagesimportbuild_manpages,get_build_py_cmd,get_install_cmdsetup([...]cmdclass={'build_manpages':build_manpages,# Re-define build_py and install commands so the manual pages# are automatically re-generated and installed'build_py':get_build_py_cmd(),'install':get_install_cmd(),})And insetup.cfgconfigure the manual pages you want to automatically
generate and install:[build_manpages]
manpages =
    man/foo.1:object=parser:pyfile=bin/foo.py
    man/bar.1:function=get_parser:pyfile=bin/bar
    man/baz.1:function=get_parser:pyfile=bin/bar:prog=bazList of manual pagesThe format of those lines is a colon separated list of arguments/options.  The
first argument determines the filename of the generated manual page.  Then
follows a list of options of formatoption=value.  Supported values are:pyfile - what python file the argparse object resides inobject - the name of arparse object in "pyfile" to importfunction - the name of function in pyfile to call to get the argparse objectformat - format of the generated man page:pretty(default),single-commands-sectionauthor - author of the program; can be specified multiple timesdescription - description of the program, used in the NAME section, after the
leading 'name - ' part, see man (7) man-pages for more infoproject_name - name of the project the program is part ofversion - version of the project, visible in manual page footerprog - value that substitutes %prog in ArgumentParser's usageurl - link to project download pagemanual_section - section of the manual, by default 1, see man (7) man-pages
for more info about existing sectionsmanual_title - the title of the manual, by default "Generated Python Manual",
see man (7) man-pages for more instructionsinclude - a file of extra material to include; see below for the formatmanfile - a file containing a complete man page that just needs to be installed
(such files must also be listed inMANIFEST.in)The values from setup.cfg override values from setup.py's setup(). Note that
whenmanfileis set for a particular page, no other option is allowed.Then runsetup.py build_manpagesto build a manpages for your project.  Also,
if you usedget_build_pyhelper,setup.py buildthen transitively builds the
manual pages.Include file formatThe include file format is based on GNUhelp2man's--includeformat.The format is simple:[section]
text

/pattern/
textBlocks of verbatim *roff text are inserted into the output either at
the start of the givensection(case insensitive), or after a
paragraph matchingpattern, a Python regular expression.Lines before the first section are silently ignored and may be used for
comments and the like.Other sections are prepended to the automatically produced output for the
standard sections given above, or included near the bottom of the man page,
before theAUTHORsection, in the order they occur in the include file.Placement of the text within the section may be explicitly requested by
using the syntax[<section],[=section]or[>section]to place the
additional text before, in place of, or after the default output
respectively.InstallationThis package is distributedin PyPI, can be installed by:$ pip install argparse-manpageIt can simply downloaded, or distributed as a git submodule (see above).Packaging statusThe Git snapshot RPMs–pre-release version automatically built from themainbranch–are available in Fedora Copr build systemTheargparse-manpageproject is provided natively on many distributions:Try your package manager directly (e.g. on Fedoradnf install -y argparse-manpage).HistoryThe initial code was developed for CrunchyFrog, a database query tool for Gnome.
Thefrogis now retired andRunSQLRunis it's successor.  Then, thebuild_manpagecommand was developed inandialbrechtand edited slightly
ingabrielegiammatteo.  There's even anold blog postabout this command.Since some useful work has been done inpython pull request, the code from the
PR has been used here too.Later more options and flexibility has been implemented in this fork, with the
help of many contributors.  Thank you!Historically,build_manpagesetup.py command was provided (mostly forOptionParser).  Later we migrated to more versatilebuild_manpagescommand.
But the old variant is stillsupported.LicenseThis work is released under the terms of the Apache License v2.0.
See LICENSE for details.[^1]:argparse-manpageneeds to process the location (file/module) via Python
interpreter, and thus please avoid side-effects (typically, themain.pyfiles need to use theif __name__ == "__main__"condition, and similar).