Package | |
Meta |
This provides
a build hook plugin
for Hatch to automatically generate a
manual page from an ArgumentParser
object,
using argparse-manpage
by Pavel Raiskup.
Table of Contents
This plugin is not an official project of 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.
The build hook plugin
name is argparse-manpage
.
Modify pyproject.toml
to include the plugin as a build dependency:
[build-system]
requires = ["hatchling", "hatch-argparse-manpage"]
build-backend = "hatchling.build"
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.
For example:
[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",
]
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:
- If a homepage URL is specified, then it is used.
- 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):
[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",
]
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):
[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",
]
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.
The code to parse the pyproject.toml config in this plugin overlaps with the code in 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.
GNU gettext users may be interested in hatch-gettext.
hatch-argparse-manpage
is distributed under the terms of
the GPL-3.0-or-later license.