iiif-prezi / iiif-prezi3

IIIF Presentation API 3 Python Library
https://iiif-prezi.github.io/iiif-prezi3/
Apache License 2.0
28 stars 14 forks source link

mkdocs is not currently buillding documentation from the docstrings #130

Closed digitaldogsbody closed 1 year ago

digitaldogsbody commented 1 year ago

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/

helrond commented 1 year ago

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.

digitaldogsbody commented 1 year ago

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

digitaldogsbody commented 1 year ago

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/.*

digitaldogsbody commented 1 year ago

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 :/ Screenshot at 2022-12-06 12-19-39

digitaldogsbody commented 1 year ago

If I changecode.md to be e.g ::: iiif_prezi3.helpers.AddItem then I get the generation for that helper class ok

rlskoeser commented 1 year ago

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.

glenrobson commented 1 year ago

Hillel to have a look the code option in: https://github.com/iiif-prezi/iiif-prezi3/issues/130#issuecomment-1335992990 but @rlskoeser if you've got time we could do with your help :-)

rlskoeser commented 1 year ago

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.

digitaldogsbody commented 1 year ago

https://github.com/mkdocstrings/python/issues/36

This might be the answer!

digitaldogsbody commented 1 year ago

mkdocstrings/python#36

This might be the answer!

Yes! PR incoming...