hatch-mkdocs

Hatch插件，用于将MkDocs集成到环境中并推断依赖关系

此插件根据mkdocs.yml文件动态填充Hatch环境中的dependencies。

此插件旨在轻松管理MkDocs网站的依赖关系。

您只需将此最小配置添加到Hatch中，以及任何现有的MkDocs配置

[env]
requires = [
    "hatch-mkdocs",
]

[env.collectors.mkdocs.docs]
path = "mkdocs.yml"

site_name: MkDocs example

plugins:
  - autorefs

markdown_extensions:
  - callouts
  - pymdownx.superfences

[envs.docs]
detached = true
dependencies = [
    "markdown-callouts",
    "mkdocs",
    "mkdocs-autorefs",
    "pymdown-extensions",
]

[envs.docs.scripts]
build = "mkdocs build -f mkdocs.yml {args}"
serve = "mkdocs serve -f mkdocs.yml {args}"
gh-deploy = "mkdocs gh-deploy -f mkdocs.yml {args}"

有了这个

• 您不需要指定PyPI依赖项，它们将根据mkdocs.yml进行反向查找MkDocs插件目录，使用mkdocs get-deps进行推断。（更多详情见此处）

• 一个自动管理的虚拟环境，其中包含预定义的MkDocs命令，尽在掌握之中。

您可以自己检查

                    Standalone                     
┌──────┬─────────┬────────────────────┬───────────┐
│ Name │ Type    │ Dependencies       │ Scripts   │
├──────┼─────────┼────────────────────┼───────────┤
│ docs │ virtual │ markdown-callouts  │ build     │
│      │         │ mkdocs             │ gh-deploy │
│      │         │ mkdocs-autorefs    │ serve     │
│      │         │ pymdown-extensions │           │
└──────┴─────────┴────────────────────┴───────────┘

依赖关系将在Hatch调用的过程中解析并安装到虚拟环境中。因此，您可以直接运行

Creating environment: docs
Checking dependencies
Syncing dependencies
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: site
INFO    -  Documentation built in 0.03 seconds

（如果您直接使用virtualenvs，则此单个命令可以替代创建环境、将依赖项安装到其中，以及在其中运行mkdocs，可选地带有参数）

此外，每当依赖项集合发生变化时（即您选择新的MkDocs插件），这些Hatch命令将根据需要重新安装依赖项。
否则，将重用环境；安装仅在第一次调用时发生。

如果您在任何时候想确保重新安装依赖项，只需删除环境即可

Removing environment: docs

安装

只需安装Hatch。理想情况下，使用pipx install hatch以隔离的方式安装，或者只是pip install hatch作为更常见的安装方式。

如果您在Hatch配置（如上所示）中将hatch-mkdocs声明为依赖项（pyproject.toml或hatch.toml），Hatch将在第一次使用时自动安装它。

或者您可以手动安装：pipx inject hatch hatch-mkdocs或直接pip install hatch-mkdocs。

不要安装MkDocs - 它是不必要的，只有子环境将拥有它。

配置

请注意，尽管Hatch通常与管理和维护整个Python项目和应用程序相关联，但您可以使用它仅用于MkDocs站点的环境管理 - 通过此插件，甚至不使用它。

Hatch可以通过两个文件之一进行配置 - hatch.toml或pyproject.toml。后者中的配置等效，但始终需要[tool.hatch...]前缀；如果您的Python项目已存在并且您不想添加另一个配置文件，则可以使用它。

因此，将以下内容添加到其中一个文件中

[env]
requires = [
    "hatch-mkdocs",
]

[env.collectors.mkdocs.ENV_NAME]
path = "path/to/mkdocs.yml"

[envs.ENV_NAME]
...

[tool.hatch.env]
requires = [
    "hatch-mkdocs"
]

[tool.hatch.env.collectors.mkdocs.ENV_NAME]
path = "path/to/mkdocs.yml"

[tool.hatch.envs.ENV_NAME]
...

在这里，[env.collectors.mkdocs.ENV_NAME]意味着：请根据MkDocs配置填充名为"ENV_NAME"的环境。在该部分中，path是mkdocs.yml的路径。

目前，这就是此插件的全部可配置性。

在第一个示例中，我们使用了"docs"作为环境名称，如果您喜欢，也可以使用"mkdocs"，或者任何其他名称。此外，如果您使用"default"作为名称（如果您只需使用Hatch进行文档构建，则可能这样做），则可以省略环境前缀（如上例中的docs:）。

也可以填充具有各自配置和依赖项的多个单独环境。

在[envs.ENV_NAME]内部（这是Hatch中的一个普通结构）中，您可以进一步自定义环境（尽管通常不需要这样做，并且可以省略该部分）：您可以添加额外的dependencies或scripts，或任何其他环境配置。您还可以将detached设置回false，如果文档确实依赖于项目本身被安装，例如在mkdocstrings的情况下。