pawamoy
commented
1 year ago Hello, thanks for the report.
The reproduction instructions are not super maintainer friendly. They shouldn't depend on a particular IDE. Ideally, you'd provide a few command lines. Here's what I ended up doing to have a working environment:
git clone https://chacha.ddns.net/gitea/chacha/pygamecfg
cd pygamecfg
python -m venv .venv
. .venv/bin/activate
pip install mkdocs
pip install $(mkdocs get-deps)But the docs folder does not exist, it has to be generated. Looking at your project it seems to be done thanks to the helpers, though these helpers require additional dependencies. After a lot of back and forth, I ended up installing your project and its optional dependencies:
pip install -e .[test,coverage-check,complexity-check,quality-check,type-check,doc-gen]Then I was able to run python -m helpers --help to learn that I could run python -m helpers --doc-gen to finally try and build the docs.
In the end, this is what I would have wanted to see:
git clone https://chacha.ddns.net/gitea/chacha/pygamecfg
cd pygamecfg
python -m venv .venv
. .venv/bin/activate
pip install -e .[test,coverage-check,complexity-check,quality-check,type-check,doc-gen]
python -m helpers --doc-gen
mkdocs serveI hope this will help you creating better reports in the future :slightly_smiling_face:
Now about your issue. You are referencing your modules with ::: src.pygamecfg. This is wrong: your Python package is not src, it's pygamecfg, so the references should look like ::: pygamecfg.data, etc. In your helpers, you are voluntarily adding src to the paths: identifier = "src." + ".".join(parts). I suppose you did this because without it, mkdocstrings wouldn't find your modules? The proper way to tell mkdocstrings how to find your modules under src is to use the paths option.
plugins:
- mkdocstrings:
handlers:
python:
paths: [src]Then remove the src. prefix from your autodoc instructions (::: pygamecfg.data, etc.), and it should work better.
I tested it locally and it fixes the issue, so I'll close this, but feel free to comment further!
cclecle
Describe the bug On at least one of my project (all using same configuration), I have most python modules missing in the generated documentation. See my mkdocs.yml. See the generated documentation, go to reference, there is only tool_ini, while I expect having all my modules.
To Reproduce clone this repo in eclipse (pydev project): pygamecfg dev install deps in your python venv: ["mkdocs>=1.4.0", "mkdocs-material>=8.5","mkdocs-material-extensions","mkdocs-pymdownx-material-extras", "mkdocs-localsearch>=0.9.0", "mkdocstrings[python]>=0.19", "mkdocs-with-pdf>=0.9.3","pyyaml>=6.0","pymdown-extensions>=9","mkdocs-markdownextradata-plugin","mkdocs-mermaid2-plugin","mkdocs-autorefs"] runs: RUN_mkdocs.launch with eclipse (right click-> Run_As), then find the generated doc in the doc/ subdirectory
I also tried (without improvment):
Also: In my other successfully working project(s) (with same mkdocs.yml, just right names), I can see multiple lines:
DEBUG - mkdocstrings: Matched '::: src.<package>.<module>On per generated module. But in this one, I see only one single line:DEBUG - mkdocstrings: Matched '::: src.pygamecfg.tool_ini'And tool_ini is the only generated autodoc.Expected behavior The generated documentation should contain all the python modules except
__init__and__main__(filter).System (please complete the following information):
mkdocstrings-pythonversion: last available on pypiMkdocs logs