Failed to build documentation locally

Open

#465 opened on Jun 22, 2023 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty: 3/5
Estimated time: 1-2 days
Newbie friendliness: 35/100

Issue type: Bug
Clarity: Mostly clear
Activity status: Stale
Tech stack: python
Domain: build-system, documentation

Research direction

Start with CONTRIBUTING.md and requirements-docs.txt, then reproduce the failure by running mkdocs serve in the documentation setup. Check why the mdx_truly_sane_lists extension and mkdocstrings plugin cannot be loaded with the listed packages. Done means the documented local publishing workflow builds without these configuration errors.

Written by the indexing model from the issue text.

Description

I encounter an error when publishing documentation locally using mkdocs according to the CONTRIBUTING.md doc.

After installing the requirements-docs.txt, I run the mkdocs serve command, and there is an error says:

INFO     -  Building documentation...
ERROR    -  Config value: 'markdown_extensions'. Error: Failed loading extension "mdx_truly_sane_lists".
ERROR    -  Config value: 'plugins'. Error: The "mkdocstrings" plugin is not installed
Aborted with 2 Configuration Errors!

Here is my installed packages:

$ pip freeze
astunparse==1.6.3
click==8.1.3
colorama==0.4.6
ghp-import==2.1.0
griffe==0.29.1
importlib-metadata==6.7.0
Jinja2==3.1.2
Markdown==3.3.7
MarkupSafe==2.1.3
mdx-truly-sane-lists==1.3
mergedeep==1.3.4
mkdocs==1.3.1
mkdocs-autorefs==0.4.1
mkdocs-include-markdown-plugin==3.3.0
mkdocs-material==8.2.16
mkdocs-material-extensions==1.1.1
mkdocstrings==0.18.1
mkdocstrings-python==0.6.6
mkdocstrings-python-legacy==0.2.2
packaging==23.1
Pygments==2.15.1
pymdown-extensions==10.0.1
python-dateutil==2.8.2
-e git+https://github.com/theskumar/python-dotenv.git@137bc3dc0b8cf3d417a1e800c4065c526e3fb96a#egg=python_dotenv
pytkdocs==0.16.1
PyYAML==6.0
pyyaml_env_tag==0.1
six==1.16.0
watchdog==3.0.0
zipp==3.15.0

System:

macOS Ventura 13.4 on Apple M1 MacBook Air
Python 3.8.12

Dominant language: Python
Stars: 8.9k
Forks: 581
PR merge metrics: No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Similar issues

Use `charmlibs.interfaces.oauth` instead of deprecated `hydra.oauth` Open

enhancement

Difficulty 2/5 1-3 hours Newbie friendliness 70/100

canonical/paas-charm#368 · 1 comment · Opened Sep 23, 2026
Model API: distributable field returns false even when "Allow Distributed Inference Across Workers" is checked Open

Difficulty 2/5 1-3 hours Newbie friendliness 75/100

gpustack/gpustack#6275 · Opened Sep 23, 2026
attachment_urls parameter descriptions do not state that the value must be a reference Open

tech debt

Difficulty 2/5 1-3 hours Newbie friendliness 75/100

epam/ai-dial-quickapps-backend#579 · Opened Sep 23, 2026
addition to tracking list Open

Difficulty 1/5 Under an hour Newbie friendliness 90/100

StevenBlack/hosts#3256 · Opened Sep 23, 2026
Fix-WebUI-README-screenshot-links Open

Difficulty 1/5 Under an hour Newbie friendliness 90/100

qualcomm/qai-appbuilder#275 · Opened Sep 23, 2026

More Python issues