ansible / ansible/mkdocs-ansible
install_from_adt's `pip3 install` recommendation fails with externally-managed-environment since PEP 668
- 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