GitLocker: The Coding Marketplace

Description:

hatchargparsemanpage 1.0.0

Hatch Argparse Manpage

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

Hatch Argparse Manpage

Explanation
Configuration

Calling the plugin
Generating the manual page
Extra options

Project URLs
Argparse-manpage invocation

Cleaning output files
History
Related Hatch plugin
License

Explanation
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.
Configuration
The build hook plugin
name is argparse-manpage.
Calling the plugin
Modify pyproject.toml to include the plugin as a build dependency:
[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.
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",
]

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:

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",
]

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):
[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,
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.
License
hatch-argparse-manpage is distributed under the terms of
the GPL-3.0-or-later license.