ArgumentParser实例 → 手册页

避免在两个地方记录您的Python脚本参数！这通常在argparse.ArgumentParser 帮助配置（help=，description=等）以及手动构建的手册页中完成。

ArgumentParser 对象的优点是它实际上提供了一个可遍历的“树状”结构，包含生成文档所需的所有必要信息，例如在groff排版系统中（手册页）。这正是这个项目能够提供帮助的地方。

有两种生成手册的方法，要么使用已安装的命令argparse-manpage脚本来编写，要么通过setup.py build自动化（使用setup.py install自动安装手册页的好处）。

需要什么？

大部分（元）数据存储在ArgumentParser对象中，因此argparse-manpage需要知道其位置——可以是对象本身，也可以是获取对象的方法 [^1]。

此外，还需要指定几个手册页字段（如author或project名称）的值，这些值可以通过命令行或通过setup.py元数据来指定。

命令行用法

请看以下示例

$ 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

这个（a）处理./pythonfile.py，（b）调用内部的get_parser以获取ArgumentParser实例，（c）将其转换为手册页，并（d）存储到cool-manpage.1文件中。

或者，上述选项可以与以下选项组合使用

• 选项--module mymodule.main，从PYTHONPATH加载Python模块mymodule.main，或者
• --object parser_object_name 如果parser_object_name是全局变量。

使用pyproject.toml

首先，您需要在pyproject.toml中声明需要在构建时使用argparse-manpage，并使用setuptools.builds_meta`后端

[build-system]
requires = ["argparse-manpage[setuptools]"]
build-backend = "setuptools.build_meta"

或者，您可以将此项目的build_manpages（子）目录放置在PYTHONPATH中的某个位置，以便在构建时使用它。例如

git submodule add --name build_manpages https://github.com/praiskup/build_manpages
git submodule update --init

然后在 pyproject.toml 中（重新）定义 cmdclass 命令

[tool.setuptools.cmdclass]
build_py = "build_manpages.build_py"
install = "build_manpages.install"
build_manpages = "build_manpages.build_manpages"

并指定构建的文档页面列表

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

与 setup.py 一起使用

在你的 setup.py 中使用以下模式

[...]
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(),
  }
)

并在 setup.cfg 中配置要自动生成和安装的文档页面

[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

文档页面列表

这些行的格式是冒号分隔的参数/选项列表。第一个参数确定生成的文档页面的文件名。然后是格式为 option=value 的选项列表。支持以下值：

• pyfile - argparse 对象所在的 Python 文件
• object - 要从 "pyfile" 中导入的 arparse 对象的名称
• function - 在 pyfile 中调用的函数的名称，用于获取 argparse 对象
• format - 生成的 man 页面的格式：pretty（默认），single-commands-section
• author - 程序的作者；可以多次指定
• description - 程序的描述，用于 NAME 部分，在 "name - " 部分的开头之后，有关更多信息请参阅 man (7) man-pages
• project_name - 程序所属的项目名称
• version - 项目的版本，在文档页面的页脚中可见
• prog - 替换 ArgumentParser 的用法中的 %prog 的值
• url - 项目下载页面的链接
• manual_section - 文档的章节，默认为 1，有关现有章节的更多信息请参阅 man (7) man-pages
• manual_title - 文档的标题，默认为 "Generated Python Manual"，有关更多信息请参阅 man (7) man-pages
• include - 包含额外材料的文件；有关格式请参阅下文
• manfile - 包含完整 man 页面的文件，只需安装（此类文件还必须列在 MANIFEST.in 中）

setup.cfg 中的值覆盖 setup.py 的 setup() 中的值。注意，当为特定页面设置了 manfile 时，不允许其他选项。

然后运行 setup.py build_manpages 为你的项目构建文档页面。另外，如果你使用了 get_build_py 辅助函数，那么 setup.py build 将递归地构建文档页面。

包含文件格式

包含文件格式基于 GNU help2man 的 --include 格式。

格式很简单

[section]
text

/pattern/
text

将 verbatim *roff 文本块插入到输出中，位于给定的 section（不区分大小写）的开始处，或者匹配 pattern 的段落之后，其中 pattern 是 Python 正则表达式。

第一行之前的行被静默忽略，可用于注释等。

其他章节被添加到上述标准章节自动生成的输出之前，或者在 man 页面的底部附近包含，在 AUTHOR 章节之前，按照它们在包含文件中出现的顺序。

可以使用语法 [<section>]、[=section] 或 [>section] 明确请求文本在章节中的位置，分别放置在默认输出之前、在默认输出中或之后。

安装

此软件包在 PyPI 上分发，可以通过以下方式安装

$ pip install argparse-manpage

它可以简单地下载，或者作为 git 子模块分发（请参阅上文）。

打包状态

Git 快照 RPM - 从 main 分支自动构建的预发布版本 - 可在 Fedora Copr 构建系统中获取

许多发行版都原生提供了 argparse-manpage 项目

直接尝试你的软件包管理器（例如，在 Fedora 上 dnf install -y argparse-manpage）。

历史记录

最初的代码是为CrunchyFrog开发的，这是一个用于Gnome的数据库查询工具。现在青蛙已经退役，其继任者是RunSQLRun。随后，在andialbrecht中开发了build_manpage命令，并在gabrielegiammatteo中稍作编辑。甚至还有一篇关于这个命令的旧博客文章。

由于在python pull request中完成了一些有用的工作，这里也使用了PR中的代码。

后来，在许多贡献者的帮助下，在这个分支中实现了更多的选项和灵活性。谢谢大家！

从历史上看，build_manpage setup.py命令提供了（主要是为OptionParser）。后来我们迁移到了更通用的build_manpages命令。但旧版本仍然受支持。

许可协议

本作品根据Apache License v2.0条款发布。有关详细信息，请参阅LICENSE。

[^1]: argparse-manpage需要通过Python解释器处理位置（文件/模块），因此请避免副作用（通常，main.py文件需要使用if __name__ == "__main__"条件，以及类似）。