# Hatch Argparse Manpage
| | |
|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Package | [](https://pypi.org/project/hatch-argparse-manpage) [](https://pypi.org/project/hatch-argparse-manpage) |
| Meta | [](https://github.com/pypa/hatch) [](https://github.com/astral-sh/ruff) [](https://gitbutler.com/) [](http://mypy-lang.org/) [](https://www.gnu.org/licenses/gpl-3.0) [](https://github.com/sponsors/damonlynch) |
-----
This provides
a [build hook](https://hatch.pypa.io/latest/config/build/#build-hooks) plugin
for [Hatch](https://github.com/pypa/hatch) to automatically generate a
manual page from an `ArgumentParser` object,
using [argparse-manpage](https://github.com/praiskup/argparse-manpage)
by [Pavel Raiskup](https://github.com/praiskup).
**Table of Contents**
* [Hatch Argparse Manpage](#hatch-argparse-manpage)
* [Explanation](#explanation)
* [Configuration](#configuration)
* [Calling the plugin](#calling-the-plugin)
* [Generating the manual page](#generating-the-manual-page)
* [Extra options](#extra-options)
* [Project URLs](#project-urls)
* [Argparse-manpage invocation](#argparse-manpage-invocation)
* [Cleaning output files](#cleaning-output-files)
* [History](#history)
* [Related Hatch plugin](#related-hatch-plugin)
* [License](#license)
## Explanation
This plugin is not an official project of
[argparse-manpage](https://github.com/praiskup/argparse-manpage).
Instead, it acts as a wrapper around it, making it available to Hatch users.
As such, if argparse-manpage changes in ways incompatible with this
plugin, this plugin may not function as expected.
This plugin has been tested against argparse-manpage version 4.5.
## Configuration
The [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/)
name is `argparse-manpage`.
### Calling the plugin
Modify `pyproject.toml` to include the plugin as a build dependency:
```toml
[build-system]
requires = ["hatchling", "hatch-argparse-manpage"]
build-backend = "hatchling.build"
```
### Generating the manual page
This plugin requires the directories storing the generated man pages are
within the project's base directory, and are not equal to the project's base
directory.
For example, for a project named `myproject`, and a src layout
`src/myproject`, an acceptable directory in which to store a
man page would be `man`.
Using the configuration option `[tool.hatch.build.hooks.argparse-manpage]`,
specify the man pages using the format defined by
[argparse-manpage](https://github.com/praiskup/argparse-manpage).
For example:
```toml
[tool.hatch.build.hooks.argparse-manpage]
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",
]
```
### Extra options
#### Project URLs
If a URL is not specified in the man page's build configuration, this plugin
extracts it from the `[project.urls]` section of the project's pyproject.toml:
1. If a homepage URL is specified, then it is used.
2. If not, if only one URL is specified, it is used.
Argparse-manpage uses a project URL to
generate a man section that explains where to download the program the
page is being built for.
To suppress this behavior, set `include-url` to false (the default value is
true):
```toml
[tool.hatch.build.hooks.argparse-manpage]
include-url = false
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",
]
```
#### Argparse-manpage invocation
This plugin defaults to calling argparse-manpage's Python code directly. If
this generates an exception, this plugin will attempt to call argparse-manpage
as a command line program. To force the use of argparse-manpage as a
command line program, set `force-command-line` to true (the default value is
false):
```toml
[tool.hatch.build.hooks.argparse-manpage]
force-command-line = true
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",
]
```
## Cleaning output files
The plugin includes logic to remove the files it outputs using hatch's
`clean` hook. As well as individual files, any output directories created
will also be removed, as long as these directories do not contain files
created by something other than this plugin.
## History
The code to parse the pyproject.toml config in this plugin overlaps with
the code in [argparse-manpage](https://github.com/praiskup/argparse-manpage),
but differs in that it is rewritten to conform to contemporary Python
stylistic conventions, as well as the specific needs of this plugin.
## Related Hatch plugin
GNU gettext users may be interested
in [hatch-gettext](https://github.com/damonlynch/hatch-gettext).
## License
`hatch-argparse-manpage` is distributed under the terms of
the [GPL-3.0-or-later](https://spdx.org/licenses/GPL-3.0-or-later.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "hatch-argparse-manpage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "build, documentation, hatch, help, man page, manpage, manual page, plugin, typing",
"author": null,
"author_email": "Damon Lynch <damonlynch@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1c/d4/c4ab111cf6cd370734b8bf305ba0fd15272a7a778921033d2458e72946f9/hatch_argparse_manpage-1.0.0.tar.gz",
"platform": null,
"description": "# Hatch Argparse Manpage\n\n| | |\n|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Package | [](https://pypi.org/project/hatch-argparse-manpage) [](https://pypi.org/project/hatch-argparse-manpage) |\n| Meta | [](https://github.com/pypa/hatch) [](https://github.com/astral-sh/ruff) [](https://gitbutler.com/) [](http://mypy-lang.org/) [](https://www.gnu.org/licenses/gpl-3.0) [](https://github.com/sponsors/damonlynch) |\n\n-----\n\nThis provides\na [build hook](https://hatch.pypa.io/latest/config/build/#build-hooks) plugin\nfor [Hatch](https://github.com/pypa/hatch) to automatically generate a\nmanual page from an `ArgumentParser` object,\nusing [argparse-manpage](https://github.com/praiskup/argparse-manpage)\nby [Pavel Raiskup](https://github.com/praiskup).\n\n**Table of Contents**\n\n* [Hatch Argparse Manpage](#hatch-argparse-manpage)\n * [Explanation](#explanation)\n * [Configuration](#configuration)\n * [Calling the plugin](#calling-the-plugin)\n * [Generating the manual page](#generating-the-manual-page)\n * [Extra options](#extra-options)\n * [Project URLs](#project-urls)\n * [Argparse-manpage invocation](#argparse-manpage-invocation)\n * [Cleaning output files](#cleaning-output-files)\n * [History](#history)\n * [Related Hatch plugin](#related-hatch-plugin)\n * [License](#license)\n\n## Explanation\n\nThis plugin is not an official project of\n[argparse-manpage](https://github.com/praiskup/argparse-manpage).\nInstead, it acts as a wrapper around it, making it available to Hatch users.\nAs such, if argparse-manpage changes in ways incompatible with this \nplugin, this plugin may not function as expected.\n\nThis plugin has been tested against argparse-manpage version 4.5.\n\n## Configuration\n\nThe [build hook plugin](https://hatch.pypa.io/latest/plugins/build-hook/)\nname is `argparse-manpage`.\n\n### Calling the plugin\n\nModify `pyproject.toml` to include the plugin as a build dependency:\n\n```toml\n[build-system]\nrequires = [\"hatchling\", \"hatch-argparse-manpage\"]\nbuild-backend = \"hatchling.build\"\n```\n\n### Generating the manual page\n\nThis plugin requires the directories storing the generated man pages are \nwithin the project's base directory, and are not equal to the project's base \ndirectory.\n\nFor example, for a project named `myproject`, and a src layout\n`src/myproject`, an acceptable directory in which to store a\nman page would be `man`.\n\nUsing the configuration option `[tool.hatch.build.hooks.argparse-manpage]`, \nspecify the man pages using the format defined by \n[argparse-manpage](https://github.com/praiskup/argparse-manpage). \n\nFor example:\n```toml\n[tool.hatch.build.hooks.argparse-manpage]\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### Extra options\n\n#### Project URLs\nIf a URL is not specified in the man page's build configuration, this plugin\nextracts it from the `[project.urls]` section of the project's pyproject.toml:\n\n1. If a homepage URL is specified, then it is used.\n2. If not, if only one URL is specified, it is used.\n\nArgparse-manpage uses a project URL to \ngenerate a man section that explains where to download the program the \npage is being built for. \n\nTo suppress this behavior, set `include-url` to false (the default value is \ntrue):\n```toml\n[tool.hatch.build.hooks.argparse-manpage]\ninclude-url = false\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#### Argparse-manpage invocation\n\nThis plugin defaults to calling argparse-manpage's Python code directly. If \nthis generates an exception, this plugin will attempt to call argparse-manpage \nas a command line program. To force the use of argparse-manpage as a \ncommand line program, set `force-command-line` to true (the default value is \nfalse):\n```toml\n[tool.hatch.build.hooks.argparse-manpage]\nforce-command-line = true\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## Cleaning output files\n\nThe plugin includes logic to remove the files it outputs using hatch's\n`clean` hook. As well as individual files, any output directories created\nwill also be removed, as long as these directories do not contain files\ncreated by something other than this plugin.\n\n## History\n\nThe code to parse the pyproject.toml config in this plugin overlaps with\nthe code in [argparse-manpage](https://github.com/praiskup/argparse-manpage),\nbut differs in that it is rewritten to conform to contemporary Python \nstylistic conventions, as well as the specific needs of this plugin.\n\n## Related Hatch plugin\n\nGNU gettext users may be interested\nin [hatch-gettext](https://github.com/damonlynch/hatch-gettext).\n\n## License\n\n`hatch-argparse-manpage` is distributed under the terms of\nthe [GPL-3.0-or-later](https://spdx.org/licenses/GPL-3.0-or-later.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Hatch build hook plugin to generate manual pages",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/damonlynch/hatch-argparse-manpage#readme",
"Homepage": "https://github.com/damonlynch/hatch-argparse-manpage",
"Issues": "https://github.com/damonlynch/hatch-argparse-manpage/issues"
},
"split_keywords": [
"build",
" documentation",
" hatch",
" help",
" man page",
" manpage",
" manual page",
" plugin",
" typing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a7f4e92049e7ec2eedf6ca1610e8755f032ed724f5e7df94afe9cc17a17bf845",
"md5": "a2b01e7e498c2260437929bf822bd335",
"sha256": "43798e418f5ca1b94c5d615af1860097b6dfb5cf0cdbfdb34674e767ea285d40"
},
"downloads": -1,
"filename": "hatch_argparse_manpage-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2b01e7e498c2260437929bf822bd335",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22265,
"upload_time": "2024-04-24T21:08:19",
"upload_time_iso_8601": "2024-04-24T21:08:19.981341Z",
"url": "https://files.pythonhosted.org/packages/a7/f4/e92049e7ec2eedf6ca1610e8755f032ed724f5e7df94afe9cc17a17bf845/hatch_argparse_manpage-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1cd4c4ab111cf6cd370734b8bf305ba0fd15272a7a778921033d2458e72946f9",
"md5": "caf381ba775f3708daee28f7b4047abe",
"sha256": "665155fe9d8447d95b975688e76e27e7500cd08cff98bc866234fca912e76bfd"
},
"downloads": -1,
"filename": "hatch_argparse_manpage-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "caf381ba775f3708daee28f7b4047abe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 24687,
"upload_time": "2024-04-24T21:08:18",
"upload_time_iso_8601": "2024-04-24T21:08:18.481019Z",
"url": "https://files.pythonhosted.org/packages/1c/d4/c4ab111cf6cd370734b8bf305ba0fd15272a7a778921033d2458e72946f9/hatch_argparse_manpage-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-24 21:08:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "damonlynch",
"github_project": "hatch-argparse-manpage#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hatch-argparse-manpage"
}
JSON
