ansible / ansible/mkdocs-ansible

install_from_adt's `pip3 install` recommendation fails with externally-managed-environment since PEP 668

Open
#331 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
12
Forks
15
Avg merge
4d 13h
Merged PRs (30d)
6

Description

The `install_from_adt` macro (https://github.com/ansible/mkdocs-ansible/blob/3fcadbca3afb30b9795acc046e0c74a904e8d3f5/src/mkdocs_ansible/__init__.py#L18-L33) renders a "Recommendation" box into the ansible-navigator, ansible-lint, molecule, ansible-creator, and ansible-dev-environment docs telling people to run `pip3 install ansible-dev-tools`. Since PEP 668, that fails immediately with `error: externally-managed-environment` on Ubuntu 23.04+ and Debian 12+. ansible-navigator's own per-OS install steps have the same problem with `python3 -m pip install ansible-navigator --user`.

pipx would fix it, but it's not a drop-in swap: `pipx install ansible-dev-tools` alone leaves out `ansible-lint` and friends (ansible/ansible-dev-tools#199), and even `pipx install --include-deps ansible-dev-tools` is missing the bundled collections that a plain `ansible` install gets (ansible/ansible-dev-tools#290, still open as of a comment from a few months back). So the macro's recommended command would need to be something like `pipx install --include-deps ansible-dev-tools` plus a line about the collections gap, not just a bare pipx swap.

Given how many docs sites this macro feeds, fixing it here seems like the highest-leverage place to do it.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start in src/mkdocs_ansible/__init__.py at the install_from_adt macro and inspect the generated recommendation used by the ansible-navigator, ansible-lint, molecule, ansible-creator, and ansible-dev-environment docs. Also locate ansible-navigator's per-OS installation steps. Update the guidance to account for PEP 668, pipx dependencies, and the collections gap, then verify the affected documentation output.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.