Missing documentation on installing Mkdocs development version dependencies

[pcgaustad]

I can't find any information in the documentation about installing the necessary dependencies for Mkdocs.

With Python 3.10.6 in a fairly standard Ubuntu 22.04 WSL environment I had to install the following dependencies after running pip install --editable . to be able to run mkdocs serve:

pip install markdown pymdown-extensions markdown-callouts mdx-gh-links \
    mkdocs-{redirects,click,autorefs,literate-nav} mkdocstrings[python]

Is there a more obvious way? hatch env docs also doesn't work in my case, at least. When I enter the environment ant run mkdocs serve, the output is:

ERROR    -  Config value 'markdown_extensions': Failed to load extension
            'pymdownx.highlight'.
            ModuleNotFoundError: No module named 'pymdownx'
ERROR    -  Config value 'plugins': The "redirects" plugin is not installed
Aborted with 2 Configuration Errors!

If there is a way that would work across different setups, I'd be happy to add it to the documentation.

[ofek]

hatch env docs isn't a command

[oprypin]

You're right that this isn't documented in our repo 😕

---

To build docs (installs deps implicitly):
hatch run docs:mkdocs serve

To learn about the dependencies:
hatch env show
hatch env show docs

Click to expand
hatch env show --json | jq -r ".docs.dependencies | .[]"

Markdown >=3.3.3
mdx_gh_links >=0.2
markdown-callouts >=0.3.0
mkdocs-literate-nav >=0.5.0
mkdocs-redirects >=1.0.1
pymdown-extensions >=8.0.1
mkdocstrings-python >=0.7.1
mkdocs-click >=0.8.0

To roll with your own dependency installation method:
hatch env show --json | jq -r ".docs.dependencies | .[]" > docs.requirements.txt
pip install -r docs-requirements.txt

(cc @ofek I really wish this didn't require jq)

[ofek]

Could do https://github.com/repo-helper/hatch-requirements-txt + https://hatch.pypa.io/latest/config/environment/overview/#features

[oprypin]

No, I want to go the other way, print out a requirements.txt on the fly, not store a requirements.txt file

[ofek]

You could forget the first part then and do https://hatch.pypa.io/latest/cli/reference/#hatch-dep-show-requirements

[oprypin]

Thanks. It works to show the dependencies of the main project, but I couldn't figure out how to make it show dependencies of the 'docs' env.

[ofek]

Right I'm saying you could make those a feature, which might be more of a thing soon https://discuss.python.org/t/adding-a-non-metadata-installer-only-dev-dependencies-table-to-pyproject-toml/20106/45

[ofek]

show dependencies of the 'docs' env

Please open a FR

[pcgaustad]

To build docs (installs deps implicitly):
hatch run docs:mkdocs serve

Thanks! Another way would be hatch -e docs shell, it seems,

[joho1968]

Perhaps I'm stating the obvious here, but this applies to those who want to contribute to the translation efforts. (I just ran into this while creating a Swedish translation.)