# ArgumentParser instance → manual page
Avoid documenting your Python script arguments on two places! This is typically
done in an [argparse.ArgumentParser][ap-docs] help configuration (`help=`,
`description=`, etc.), and also in a manually crafted manual page.
The good thing about an `ArgumentParser` objects is that it actually provides
a traversable "tree-like" structure, with all the necessary info needed to
**automatically generate** documentation, for example in a *groff* typesetting
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 command `argparse-manpage`, or via `setup.py build` automation (with a
slight bonus of automatic manual page installation with `setup.py install`).
## What is need?
Most of the (meta)data is stored in the `ArgumentParser` object, therefore
`argparse-manpage` needs 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 (like *author* or *project* name)
need to be specified, either on command-line or via `setup.py` metadata.
## Command-line usage
See 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.1
```
This (a) processes the `./pythonfile.py`, (b) calls the `get_parser` inside to
obtain the `ArgumentParser` instance, (c) transforms it into a manual page and
(d) stores it into the `cool-manpage.1` file.
Alternatively those options above can be combined with
- option `--module mymodule.main`, to load a Python module `mymodule.main`
from `PYTHONPATH`, or
- `--object parser_object_name` if the `parser_object_name` is a global
variable.
## Use with pyproject.toml
First, you need to declare in `pyproject.toml` that argparse-manpage is needed
at build-time and use the setuptools.builds_meta` backend:
```toml
[build-system]
requires = ["argparse-manpage[setuptools]"]
build-backend = "setuptools.build_meta"
```
Alternatively, you can place the `build_manpages` (sub)directory from this
project somewhere onto `PYTHONPATH` so you can use it at build time. For
example:
```bash
git submodule add --name build_manpages https://github.com/praiskup/build_manpages
git submodule update --init
```
Then in `pyproject.toml` (re)define `cmdclass` commands:
```toml
[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:
```toml
[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.py
In your `setup.py` use pattern like:
```python
[...]
from build_manpages import build_manpages, get_build_py_cmd, get_install_cmd
setup(
[...]
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 in `setup.cfg` configure 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=baz
```
## List of manual pages
The 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 format `option=value`. Supported values are:
- pyfile - what python file the argparse object resides in
- object - the name of arparse object in "pyfile" to import
- function - the name of function in pyfile to call to get the argparse object
- format - format of the generated man page: `pretty` (default), `single-commands-section`
- author - author of the program; can be specified multiple times
- description - description of the program, used in the NAME section, after the
leading 'name - ' part, see man (7) man-pages for more info
- project_name - name of the project the program is part of
- version - version of the project, visible in manual page footer
- prog - value that substitutes %prog in ArgumentParser's usage
- url - link to project download page
- manual_section - section of the manual, by default 1, see man (7) man-pages
for more info about existing sections
- manual_title - the title of the manual, by default "Generated Python Manual",
see man (7) man-pages for more instructions
- include - a file of extra material to include; see below for the format
- manfile - a file containing a complete man page that just needs to be installed
(such files must also be listed in `MANIFEST.in`)
The values from setup.cfg override values from setup.py's setup(). Note that
when `manfile` is set for a particular page, no other option is allowed.
Then run `setup.py build_manpages` to build a manpages for your project. Also,
if you used `get_build_py` helper, `setup.py build` then transitively builds the
manual pages.
## Include file format
The include file format is based on GNU `help2man`'s `--include` format.
The format is simple:
```
[section]
text
/pattern/
text
```
Blocks of verbatim *roff text are inserted into the output either at
the start of the given `section` (case insensitive), or after a
paragraph matching `pattern`, 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 the `AUTHOR` section, 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.
## Installation
This package is distributed [in PyPI][pypi-page], can be installed by:
$ pip install argparse-manpage
It can simply downloaded, or distributed as a git submodule (see above).
## Packaging status
The Git snapshot RPMs–pre-release version automatically built from the `main`
branch–are available in Fedora Copr build system
[](https://copr.fedorainfracloud.org/coprs/praiskup/argparse-manpage-ci/)
The `argparse-manpage` project is provided natively on many distributions:
Try your package manager directly (e.g. on Fedora `dnf install -y
argparse-manpage`).
## History
The initial code was developed for CrunchyFrog, a database query tool for Gnome.
The [frog] is now retired and [RunSQLRun] is it's successor. Then, the
`build_manpage` command was developed in [andialbrecht] and edited slightly
in [gabrielegiammatteo]. There's even an [old blog post] about this command.
Since some useful work has been done in [python 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_manpage` setup.py command was provided (mostly for
`OptionParser`). Later we migrated to more versatile `build_manpages` command.
But the old variant is still [supported](examples/old\_format/README.md).
## License
This work is released under the terms of the Apache License v2.0.
See LICENSE for details.
[^1]: `argparse-manpage` needs to process the location (file/module) via Python
interpreter, and thus please avoid side-effects (typically, the `main.py`
files need to use the `if __name__ == "__main__"` condition, and similar).
[gabrielegiammatteo]: https://github.com/andialbrecht/build\_manpage
[andialbrecht]: https://github.com/andialbrecht/build\_manpage
[frog]: http://crunchyfrog.googlecode.com/svn/
[RunSQLRun]: https://github.com/andialbrecht/runsqlrun
[old blog post]: https://andialbrecht.wordpress.com/2009/03/17/creating-a-man-page-with-distutils-and-optparse/
[python pull request]: https://github.com/python/cpython/pull/1169
[ap-docs]: https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser
[pypi-page]: https://pypi.org/project/argparse-manpage/
Raw data
{
"_id": null,
"home_page": "https://github.com/praiskup/argparse-manpage",
"name": "argparse-manpage",
"maintainer": "Pavel Raiskup",
"docs_url": null,
"requires_python": null,
"maintainer_email": "praiskup@redhat.com",
"keywords": null,
"author": "Gabriele Giammatteo",
"author_email": "gabriele.giammatteo@eng.it",
"download_url": "https://files.pythonhosted.org/packages/3d/b7/cacb63bd461c83050b3b0efffc9151077b69de900ef5559ffeee72fa825b/argparse-manpage-4.6.tar.gz",
"platform": null,
"description": "# ArgumentParser instance \u2192 manual page\n\nAvoid documenting your Python script arguments on two places! This is typically\ndone in an [argparse.ArgumentParser][ap-docs] help configuration (`help=`,\n`description=`, etc.), and also in a manually crafted manual page.\n\nThe good thing about an `ArgumentParser` objects is that it actually provides\na traversable \"tree-like\" structure, with all the necessary info needed to\n**automatically generate** documentation, for example in a *groff* typesetting\nsystem (manual pages). And this is where this project can help.\n\nThere are two supported ways to generate the manual, either script it using the\ninstalled command `argparse-manpage`, or via `setup.py build` automation (with a\nslight bonus of automatic manual page installation with `setup.py install`).\n\n\n## What is need?\n\nMost of the (meta)data is stored in the `ArgumentParser` object, therefore\n`argparse-manpage` needs to know its location\u2014it can be either the object\nitself, or a method to call to get the object [^1].\n\nOn top of this, several manual page fields (like *author* or *project* name)\nneed to be specified, either on command-line or via `setup.py` metadata.\n\n\n## Command-line usage\n\nSee the following example:\n\n```\n$ argparse-manpage --pyfile ./pythonfile.py --function get_parser \\\n --author \"John --author-email doe@example.com\" \\\n --project-name myproject --url https://pagure.io/myproject \\\n> cool-manpage.1\n```\n\nThis (a) processes the `./pythonfile.py`, (b) calls the `get_parser` inside to\nobtain the `ArgumentParser` instance, (c) transforms it into a manual page and\n(d) stores it into the `cool-manpage.1` file.\n\nAlternatively those options above can be combined with\n\n- option `--module mymodule.main`, to load a Python module `mymodule.main`\n from `PYTHONPATH`, or\n- `--object parser_object_name` if the `parser_object_name` is a global\n variable.\n\n\n## Use with pyproject.toml\n\nFirst, you need to declare in `pyproject.toml` that argparse-manpage is needed\nat build-time and use the setuptools.builds_meta` backend:\n\n```toml\n[build-system]\nrequires = [\"argparse-manpage[setuptools]\"]\nbuild-backend = \"setuptools.build_meta\"\n```\n\nAlternatively, you can place the `build_manpages` (sub)directory from this\nproject somewhere onto `PYTHONPATH` so you can use it at build time. For\nexample:\n\n```bash\ngit submodule add --name build_manpages https://github.com/praiskup/build_manpages\ngit submodule update --init\n```\n\nThen in `pyproject.toml` (re)define `cmdclass` commands:\n\n```toml\n[tool.setuptools.cmdclass]\nbuild_py = \"build_manpages.build_py\"\ninstall = \"build_manpages.install\"\nbuild_manpages = \"build_manpages.build_manpages\"\n```\n\nAnd specify the list of built manual pages:\n\n```toml\n[tool.build_manpages]\nmanpages = [\n \"man/foo.1:object=parser:pyfile=bin/foo.py\",\n \"man/bar.1:function=get_parser:pyfile=bin/bar\",\n \"man/baz.1:function=get_parser:pyfile=bin/bar:prog=baz\",\n]\n```\n\n## Use with setup.py\n\nIn your `setup.py` use pattern like:\n\n```python\n[...]\nfrom build_manpages import build_manpages, get_build_py_cmd, get_install_cmd\n\nsetup(\n [...]\n cmdclass={\n 'build_manpages': build_manpages,\n # Re-define build_py and install commands so the manual pages\n # are automatically re-generated and installed\n 'build_py': get_build_py_cmd(),\n 'install': get_install_cmd(),\n }\n)\n```\n\nAnd in `setup.cfg` configure the manual pages you want to automatically\ngenerate and install:\n\n```\n[build_manpages]\nmanpages =\n man/foo.1:object=parser:pyfile=bin/foo.py\n man/bar.1:function=get_parser:pyfile=bin/bar\n man/baz.1:function=get_parser:pyfile=bin/bar:prog=baz\n```\n\n## List of manual pages\n\nThe format of those lines is a colon separated list of arguments/options. The\nfirst argument determines the filename of the generated manual page. Then\nfollows a list of options of format `option=value`. Supported values are:\n\n- pyfile - what python file the argparse object resides in\n- object - the name of arparse object in \"pyfile\" to import\n- function - the name of function in pyfile to call to get the argparse object\n- format - format of the generated man page: `pretty` (default), `single-commands-section`\n- author - author of the program; can be specified multiple times\n- description - description of the program, used in the NAME section, after the\n leading 'name - ' part, see man (7) man-pages for more info\n- project_name - name of the project the program is part of\n- version - version of the project, visible in manual page footer\n- prog - value that substitutes %prog in ArgumentParser's usage\n- url - link to project download page\n- manual_section - section of the manual, by default 1, see man (7) man-pages\n for more info about existing sections\n- manual_title - the title of the manual, by default \"Generated Python Manual\",\n see man (7) man-pages for more instructions\n- include - a file of extra material to include; see below for the format\n- manfile - a file containing a complete man page that just needs to be installed\n (such files must also be listed in `MANIFEST.in`)\n\nThe values from setup.cfg override values from setup.py's setup(). Note that\nwhen `manfile` is set for a particular page, no other option is allowed.\n\nThen run `setup.py build_manpages` to build a manpages for your project. Also,\nif you used `get_build_py` helper, `setup.py build` then transitively builds the\nmanual pages.\n\n## Include file format\n\nThe include file format is based on GNU `help2man`'s `--include` format.\n\nThe format is simple:\n\n```\n[section]\ntext\n\n/pattern/\ntext\n```\n\nBlocks of verbatim *roff text are inserted into the output either at\nthe start of the given `section` (case insensitive), or after a\nparagraph matching `pattern`, a Python regular expression.\n\nLines before the first section are silently ignored and may be used for\ncomments and the like.\n\nOther sections are prepended to the automatically produced output for the\nstandard sections given above, or included near the bottom of the man page,\nbefore the `AUTHOR` section, in the order they occur in the include file.\n\nPlacement of the text within the section may be explicitly requested by\nusing the syntax `[<section]`, `[=section]` or `[>section]` to place the\nadditional text before, in place of, or after the default output\nrespectively.\n\n## Installation\n\nThis package is distributed [in PyPI][pypi-page], can be installed by:\n\n $ pip install argparse-manpage\n\nIt can simply downloaded, or distributed as a git submodule (see above).\n\n\n## Packaging status\n\nThe Git snapshot RPMs\u2013pre-release version automatically built from the `main`\nbranch\u2013are available in Fedora Copr build system\n\n[](https://copr.fedorainfracloud.org/coprs/praiskup/argparse-manpage-ci/)\n\nThe `argparse-manpage` project is provided natively on many distributions:\n\n\n\nTry your package manager directly (e.g. on Fedora `dnf install -y\nargparse-manpage`).\n\n\n## History\n\nThe initial code was developed for CrunchyFrog, a database query tool for Gnome.\nThe [frog] is now retired and [RunSQLRun] is it's successor. Then, the\n`build_manpage` command was developed in [andialbrecht] and edited slightly\nin [gabrielegiammatteo]. There's even an [old blog post] about this command.\n\nSince some useful work has been done in [python pull request], the code from the\nPR has been used here too.\n\nLater more options and flexibility has been implemented in this fork, with the\nhelp of many contributors. Thank you!\n\nHistorically, `build_manpage` setup.py command was provided (mostly for\n`OptionParser`). Later we migrated to more versatile `build_manpages` command.\nBut the old variant is still [supported](examples/old\\_format/README.md).\n\n## License\n\nThis work is released under the terms of the Apache License v2.0.\nSee LICENSE for details.\n\n\n[^1]: `argparse-manpage` needs to process the location (file/module) via Python\n interpreter, and thus please avoid side-effects (typically, the `main.py`\n files need to use the `if __name__ == \"__main__\"` condition, and similar).\n\n[gabrielegiammatteo]: https://github.com/andialbrecht/build\\_manpage\n[andialbrecht]: https://github.com/andialbrecht/build\\_manpage\n[frog]: http://crunchyfrog.googlecode.com/svn/\n[RunSQLRun]: https://github.com/andialbrecht/runsqlrun\n[old blog post]: https://andialbrecht.wordpress.com/2009/03/17/creating-a-man-page-with-distutils-and-optparse/\n[python pull request]: https://github.com/python/cpython/pull/1169\n[ap-docs]: https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser\n[pypi-page]: https://pypi.org/project/argparse-manpage/\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Build manual page from python's ArgumentParser object.",
"version": "4.6",
"project_urls": {
"Homepage": "https://github.com/praiskup/argparse-manpage"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3db7cacb63bd461c83050b3b0efffc9151077b69de900ef5559ffeee72fa825b",
"md5": "79f383caf1f1c865e3528da35a8d86ad",
"sha256": "0b659d70fd142876da41c2918bd6de4d027875720b0e4672d6443b51198dbb62"
},
"downloads": -1,
"filename": "argparse-manpage-4.6.tar.gz",
"has_sig": false,
"md5_digest": "79f383caf1f1c865e3528da35a8d86ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 58674,
"upload_time": "2024-06-05T11:46:30",
"upload_time_iso_8601": "2024-06-05T11:46:30.578318Z",
"url": "https://files.pythonhosted.org/packages/3d/b7/cacb63bd461c83050b3b0efffc9151077b69de900ef5559ffeee72fa825b/argparse-manpage-4.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-05 11:46:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "praiskup",
"github_project": "argparse-manpage",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "argparse-manpage"
}
JSON
