Skip to main content

Plugin for Hatch to infer env dependencies from mkdocs.yml

Project description

hatch-mkdocs

Hatch plugin to integrate MkDocs and infer dependencies into an env

PyPI GitHub GitHub Workflow Status

This plugin populates Hatch environments with dependencies on the fly based on a mkdocs.yml file.

This is intended to effortlessly manage dependencies for a MkDocs site.

You just need to add this minimal config to Hatch, along with any existing MkDocs config:

hatch.tomlmkdocs.yml
[env]
requires = [
    "hatch-mkdocs",
]

[env.collectors.mkdocs.docs]
path = "mkdocs.yml"
site_name: MkDocs example

plugins:
  - autorefs

markdown_extensions:
  - callouts
  - pymdownx.superfences
This gets you the following implied Hatch configuration: (click to expand)
hatch.toml
[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}"

(this is just for posterity, no such config is actually written to a file)

With this:

  • You don't need to specify the PyPI dependencies, they get inferred on the fly just from mkdocs.yml by doing a reverse lookup of MkDocs plugins in the catalog, using mkdocs get-deps. (See more details there)

  • An automatically managed virtual environment with pre-defined MkDocs commands is at your fingertips.

You can check this yourself:

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

The dependencies get resolved and installed into a virtual environment as part of a Hatch invocation. So, you can directly run:

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

(If you've been using virtualenvs directly, this single command replaces creating an environment, installing dependencies into it, as well as running mkdocs in it, optionally with arguments)

Furthermore, whenever the set of dependencies changes (i.e. you select new MkDocs plugins), these Hatch commands will re-install dependencies as necessary.
Otherwise, the environment is just reused; the installation happens only on the first invocation.

If at any point you want to make sure the dependencies are re-installed anew, you can just remove the environment:

hatch env remove docs
Removing environment: docs

Installation

Just install Hatch. Ideally in an isolated way with pipx install hatch, or just pip install hatch as a more well-known way.

If you declare hatch-mkdocs as a dependency in your Hatch config (pyproject.toml or hatch.toml) as shown above, Hatch will automatically install it on first use.

Alternatively you can install it manually: pipx inject hatch hatch-mkdocs or just pip install hatch-mkdocs.

And do not install MkDocs - it's unnecessary, only the sub-environments will have it.

Configuration

Note that although Hatch is typically associated with managing entire Python projects and applications, you can use it purely for environment management for a MkDocs site - through this plugin, or even without it.

Hatch can be configured through one of two files - hatch.toml or pyproject.toml. Configs in the latter are equivalent but will always need a [tool.hatch...] prefix; it can be used if you have an existing Python project and you don't want to add another config file.

So, add the following into one of the files:

hatch.tomlpyproject.toml
[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]
...

Here, [env.collectors.mkdocs.ENV_NAME] means: please populate an environment named "ENV_NAME" based on an MkDocs config. In that section, path is the path to mkdocs.yml.

At the moment that is the entire configurability of this plugin.

In the first example we used "docs" as the environment name, you can use "mkdocs" as well if you like, or anything else. Further, if you use "default" as the name (which you might do if documentation building is all that you'll ever use Hatch for) then you can skip the environment prefix (docs: in the above example).

Multiple separate environments with their own configs and dependencies can be populated as well.

Inside [envs.ENV_NAME] (which is an ordinary construct in Hatch) you can proceed to further customize the environment (though normally it shouldn't be necessary, and the section can be omitted from the text config): you can add extra dependencies or scripts, or any other environment config. You could also set detached back to false if the documentation actually relies on the project itself being installed, such as in the case of mkdocstrings.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hatch_mkdocs-0.1.0.tar.gz (5.4 kB view details)

Uploaded Source

Built Distribution

hatch_mkdocs-0.1.0-py3-none-any.whl (6.2 kB view details)

Uploaded Python 3

File details

Details for the file hatch_mkdocs-0.1.0.tar.gz.

File metadata

  • Download URL: hatch_mkdocs-0.1.0.tar.gz
  • Upload date:
  • Size: 5.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.6

File hashes

Hashes for hatch_mkdocs-0.1.0.tar.gz
Algorithm Hash digest
SHA256 ba775ae11435c79efeb539831d2dde29f78de07d60f126b676ddd5b230110069
MD5 e73bbbd2d41e185fd5c306ab87aad266
BLAKE2b-256 fce98152170248db151d27cdd609bd54f4c47616d710d50eb6e170b6a71fdc3e

See more details on using hashes here.

File details

Details for the file hatch_mkdocs-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: hatch_mkdocs-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 6.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.6

File hashes

Hashes for hatch_mkdocs-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4a67a57577c5093d37fa02b7b815c624e37e22c65320ff4deab98ffb6aa3d9a6
MD5 c2256551480681bf9f0844129238f34c
BLAKE2b-256 44907efd15b4c33957f47675a4c72ac9ea394023f20b737b528c691c3c76a88e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page