hatc...page(3)

✨ NAME ✨

hatch-argparse-manpage — bestie, it's a Hatch build hook plugin that generates manual pages for you. Like, it just does it. Automatically. Iconic behavior honestly 💅

---

🌸 SYNOPSIS 🌸

okay so first things first, you're gonna go tweak your pyproject.toml like this:

[build-system]
requires = ["hatchling", "hatch-argparse-manpage"]
build-backend = "hatchling.build"

[tool.hatch.build.hooks.argparse-manpage]
manpages = ["MANPAGE-BUILD-CONFIGURATION", ...]
include-url = BOOLEAN
force-command-line = BOOLEAN

that's it that's the whole vibe ✨

---

🦋 DESCRIPTION 🦋

So hatch-argparse-manpage gives you a build hook plugin for Hatch that automatically generates a manual page from an ArgumentParser object. It does this using the Python program argparse-manpage. No cap, it's literally just that 🫶

🎀 Directory layout 🎀

Heads up bestie, this plugin has rules about where your generated man pages live:

• The directories storing the generated man pages have to be within the project's base directory.
• They cannot be equal to the project's base directory. Not the same thing, periodt.

So like, say your project is named myproject and you've got a src layout of src/myproject — a perfectly acceptable directory to stash a man page in would be man 💖

🌈 Required key value 🌈

• manpages — an array of strings that specifies the build configuration for the man pages you want generated. You gotta use the format that argparse-manpage requires. That's the whole thing, iykyk.

⭐ Optional key values ⭐

• include-url — a Boolean that says whether to show the project URL in the generated man page. The default is true. See below, bestie 👇
• force-command-line — a Boolean that says whether to invoke argparse-manpage from the command line, or by calling it as a Python object. The default is false. See below again 👇

🧚 Project URLs 🧚

If a URL isn't specified in the man page's build configuration, this plugin goes and extracts it from the [project.urls] section of your project's pyproject.toml, in this order:

1. If a homepage URL is specified, then it is used. Done. Case closed.
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. And if you're like "girl I do not want that" — see above to suppress inclusion of the URL in the man page 🙈

💜 Argparse-manpage invocation 💜

By default, this plugin calls argparse-manpage's Python code directly. But if that generates an exception, this plugin will attempt to call argparse-manpage as a command line program instead. It's giving "plan b energy" honestly. See above if you wanna override this behaviour using the optional key force-command-line ✨

💖 Cleaning output files 💖

This plugin includes logic to remove the files it outputs, using hatch's clean hook. And it's not just individual files — any output directories it created will also be removed, as long as those directories don't contain files created by something other than this plugin. Like, it's not gonna delete your whole life, just its own mess 🧹

---

🔥 EXAMPLES 🔥

Generate three manpages:

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

Suppress the inclusion of the project URL:

[tool.hatch.build.hooks.argparse-manpage]
include-url = false
manpages = [
    "man/foo.1:object=parser:pyfile=bin/foo.py",
]

Force invoking argparse-manpage via the command line:

[tool.hatch.build.hooks.argparse-manpage]
force-command-line = true
manpages = [
    "man/foo.1:object=parser:pyfile=bin/foo.py",
]

---

👑 HISTORY 👑

Okay so story time 📖

This plugin is not an official project of argparse-manpage. Nope. Instead, it acts as a wrapper around it, making it available to Hatch users. And because of that, if argparse-manpage changes in ways incompatible with this plugin, this plugin may not function as expected. That's just the tea 🍵

This plugin has been tested against argparse-manpage version 4.5. 💅

The code to parse the pyproject.toml config in this plugin overlaps with the code in argparse-manpage, but it differs in that it is rewritten to conform to contemporary Python stylistic conventions, as well as the specific needs of this plugin. A glow-up, basically ✨

---

🌈 SEE ALSO 🌈

• argparse-manpage

---

💜 AUTHOR 💜

Damon Lynch damonlynch@gmail.com

---

🎀 COPYRIGHT 🎀

Copyright 2024 Damon Lynch.

---

and that's the whole page bestie 🫶 this was hatc...page(3) — section 3 of the manuals, mwah, go generate some gorgeous man pages 💖✨🎀