mkdocs is not currently buillding documentation from the docstrings
Closed this issue · 10 comments
The mkdocstrings plugin is included in https://github.com/iiif-prezi/iiif-prezi3/blob/main/mkdocs.yml and there is what I assume to be a file that should trigger it for the library in https://github.com/iiif-prezi/iiif-prezi3/blob/main/docs/code.md but the generated docs are blank for that section: https://iiif-prezi.github.io/iiif-prezi3/code/
I looked into this briefly, and it appears that mkdocstrings is expecting you to point to a module (i.e. ::: iiif_prezi3.helpers.add_item, not ::: iiif_prezi3. So, we could add references for all those modules to https://github.com/iiif-prezi/iiif-prezi3/blob/main/docs/code.md BUT that seems like a maintenance nightmare because we'd have to update that page whenever a new helper is added. There look to be some solutions for this like https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages but I haven't had the chance yet to dig in there.
Thanks Hillel. The extra modules linked on that page look promising, and if worst comes to worst, we could probably autogenerate the skeleton .md files using a script in the docs workflow
After merging @rlskoeser's fix - I am still not seeing the docstrings. However, there looks like there is something odd going on with the workflow: https://github.com/iiif-prezi/iiif-prezi3/actions/runs/3629265185/jobs/6121308959
The mkdocs step says
Building documentation to directory: /home/runner/work/iiif-prezi3/iiif-prezi3/site
but then the "upload to giuthub pages" action gets:
[INFO] copy /home/runner/work/iiif-prezi3/iiif-prezi3/site to /home/runner/actions_github_pages_1670327949848
cp: no such file or directory: /home/runner/work/iiif-prezi3/iiif-prezi3/site/.*
Running mkdocs locally in verbose mode - I see the introspection and walking through the code files:
DEBUG - mkdocstrings: Using handler 'python'
DEBUG - mkdocstrings: Collecting data
DEBUG - griffe: Found iiif_prezi3: loading
DEBUG - griffe: Loading path iiif_prezi3/__init__.py
DEBUG - griffe: Loading path iiif_prezi3/base.py
DEBUG - griffe: Loading path iiif_prezi3/skeleton_old2.py
DEBUG - griffe: Loading path iiif_prezi3/loader.py
DEBUG - griffe: Loading path iiif_prezi3/skeleton.py
DEBUG - griffe: Loading path iiif_prezi3/extensions/__init__.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/__init__.py
DEBUG - griffe: Loading path iiif_prezi3/config/__init__.py
DEBUG - griffe: Loading path iiif_prezi3/extensions/example_extension.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/set_hwd_from_iiif.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/make_range.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/add_metadata.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/set_hwd_from_file.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/add_service.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/make_manifest.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/canvas_helpers.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/add_item.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/canvas_sizes.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/add_label.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/make_canvas.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/annotation_helpers.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/make_collection.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/auto_fields.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/to_reference.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/add_range.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/set_hwd.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/make_service.py
DEBUG - griffe: Loading path iiif_prezi3/helpers/create_canvas_from_iiif.py
DEBUG - griffe: Loading path iiif_prezi3/config/config.py
DEBUG - griffe: Alias iiif_prezi3.config.configs was resolved to iiif_prezi3.config.config.configs
DEBUG - griffe: Iteration 1 finished, 1 aliases resolved, still 0 to go
DEBUG - mkdocstrings: Updating renderer's env
DEBUG - mkdocstrings: Rendering templates
DEBUG - mkdocstrings: python/templates/material/module.html: Rendering iiif_prezi3
DEBUG - mkdocstrings: python/templates/material/children.html: Rendering children of iiif_prezi3
but I am still getting nothing in the actual generated docs :/
If I changecode.md to be e.g ::: iiif_prezi3.helpers.AddItem then I get the generation for that helper class ok
drat, I forgot to check versions — when I tested locally I was apparently using an older version that what is specified in setup.py and what's being used in the github actions workflow. I don't know why that would matter, maybe there's a regression somewhere in mkdocstrings or one of the dependencies.
fwiw, while I was looking I saw that there is a mkdocs gh-deploy command; wonder if that would be any simpler than using the github pages action.
Hillel to have a look the code option in: #130 (comment) but @rlskoeser if you've got time we could do with your help :-)
FWIW, just tested locally with versions. When I install an older version with pip install "mkdocstrings-python<0.7" then the build generates output for the code page (and I get lots of warnings and errors). When I install any version newer than that, no warnings and no output in the built file. Not sure why this is, but a shorter term fix might be to use the older version — maybe there's a problem with mkdocstrings-python that will resolved in a future release.
This might be the answer!
This might be the answer!
Yes! PR incoming...