mkdocstrings: Documentation broken for an unknown reason.

Describe the bug The documentation is not building if I use mkdocstrings.

To Reproduce

  1. git clone git@github.com:kunguz/odak.git
  2. cd odak
  3. mkdocs serve

Expected behavior A running mkdocs server, which was the case until a week or a two ago, I haven’t changed anything in the meantime. But various updates took place to mkdocstrings and mkdocs-material in the meantime. I can’t interpret the issue from the terminal output. If I remove mkdocstrings related lines from my MD files, things works. If I revert to an older version of mkdocstrings things also work. Everything runs perfectly if I revert to an old version, specifically mkdocs-material==8.1.0 and mkdocstrings==0.17.0 with pytkdocs[numpy-style] support.

Information

  • Ubuntu 22.04 LTS
  • Browser: Firefox 101.0 (64-bit)
  • mkdocstrings[python] version: 0.19.0
  • mkdocs version: 1.3.0

Additional context

$ ξ‚° mkdocs serve > output.txt
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - notes/holographic_light_transport.md
  - notes/optimizing_holograms_using_odak.md
  - notes/using_metameric_loss.md
  - odak/beginning.md
  - odak/installation.md
  - odak/learn/perception/blur_loss.md
  - odak/learn/perception/make_3d_location_map.md
  - odak/learn/perception/make_eccentricity_distance_maps.md
  - odak/learn/perception/make_pooling_size_map_lod.md
  - odak/learn/perception/make_pooling_size_map_pixels.md
  - odak/learn/perception/make_radial_map.md
  - odak/learn/perception/metamer_mse_loss.md
  - odak/learn/perception/metameric_loss.md
  - odak/learn/perception/metameric_loss_uniform.md
  - odak/learn/perception/radially_varying_blur.md
  - odak/learn/perception/rgb_2_ycrcb.md
  - odak/learn/perception/spatial_steerable_pyramid.md
  - odak/learn/perception/ycrcb_2_rgb.md
  - odak/learn/wave/adjust_phase_only_slm_range.md
  - odak/learn/wave/band_limited_angular_spectrum.md
  - odak/learn/wave/calculate_amplitude.md
  - odak/learn/wave/calculate_phase.md
  - odak/learn/wave/custom.md
  - odak/learn/wave/generate_complex_field.md
  - odak/learn/wave/gerchberg_saxton.md
  - odak/learn/wave/gradient_descent.md
  - odak/learn/wave/impulse_response_fresnel.md
  - odak/learn/wave/linear_grating.md
  - odak/learn/wave/phase_gradient.md
  - odak/learn/wave/point_wise.md
  - odak/learn/wave/prism_phase_function.md
  - odak/learn/wave/produce_phase_only_slm_pattern.md
  - odak/learn/wave/propagate_beam.md
  - odak/learn/wave/quadratic_phase_function.md
  - odak/learn/wave/set_amplitude.md
  - odak/learn/wave/shift_w_double_phase.md
  - odak/learn/wave/speckle_contrast.md
  - odak/learn/wave/stochastic_gradient_descent.md
  - odak/learn/wave/transfer_function_kernel.md
  - odak/learn/wave/wavenumber.md
  - odak/tools/check_directory.md
  - odak/tools/convert_bytes.md
  - odak/tools/list_files.md
  - odak/tools/load_dictionary.md
  - odak/tools/load_image.md
  - odak/tools/resize_image.md
  - odak/tools/save_dictionary.md
  - odak/tools/save_image.md
  - odak/tools/shell_command.md
  - odak/tools/size_of_a_file.md
  - odak/wave/adaptive_sampling_angular_spectrum.md
  - odak/wave/add_phase.md
  - odak/wave/add_random_phase.md
  - odak/wave/adjust_phase_only_slm_range.md
  - odak/wave/angular_spectrum.md
  - odak/wave/band_extended_angular_spectrum.md
  - odak/wave/band_limited_angular_spectrum.md
  - odak/wave/calculate_amplitude.md
  - odak/wave/calculate_intensity.md
  - odak/wave/calculate_phase.md
  - odak/wave/double_convergence.md
  - odak/wave/electric_field_per_plane_wave.md
  - odak/wave/fraunhofer.md
  - odak/wave/fraunhofer_equal_size_adjust.md
  - odak/wave/fraunhofer_inverse.md
  - odak/wave/generate_complex_field.md
  - odak/wave/gerchberg_saxton.md
  - odak/wave/gerchberg_saxton_3d.md
  - odak/wave/impulse_response_fresnel.md
  - odak/wave/linear_grating.md
  - odak/wave/prism_phase_function.md
  - odak/wave/produce_phase_only_slm_pattern.md
  - odak/wave/propagate_beam.md
  - odak/wave/propagate_field.md
  - odak/wave/propagate_plane_waves.md
  - odak/wave/quadratic_phase_function.md
  - odak/wave/rayleigh_resolution.md
  - odak/wave/rayleigh_sommerfeld.md
  - odak/wave/rotationspeed.md
  - odak/wave/set_amplitude.md
  - odak/wave/transfer_function_kernel.md
  - odak/wave/wavenumber.md
ERROR    -  Error reading page 'odak/learn/perception/blur_loss.md': '<' not supported between instances of 'NoneType' and 'int'
Traceback (most recent call last):
  File "/home/kaan/.local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/lib/python3/dist-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/lib/python3/dist-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/lib/python3/dist-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocs/__main__.py", line 181, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 63, in serve
    config = builder()
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 58, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 292, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 174, in _populate_page
    page.render(config, files)
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocs/structure/pages.py", line 175, in render
    self.content = md.convert(self.markdown)
  File "/usr/lib/python3/dist-packages/markdown/core.py", line 264, in convert
    root = self.parser.parseDocument(self.lines).getroot()
  File "/usr/lib/python3/dist-packages/markdown/blockparser.py", line 90, in parseDocument
    self.parseChunk(self.root, '\n'.join(lines))
  File "/usr/lib/python3/dist-packages/markdown/blockparser.py", line 105, in parseChunk
    self.parseBlocks(parent, text.split('\n\n'))
  File "/usr/lib/python3/dist-packages/markdown/blockparser.py", line 123, in parseBlocks
    if processor.run(parent, blocks) is not False:
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocstrings/extension.py", line 121, in run
    html, handler, data = self._process_block(identifier, block, heading_level)
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocstrings/extension.py", line 195, in _process_block
    data: CollectorItem = handler.collect(identifier, options)
  File "/home/kaan/.local/lib/python3.10/site-packages/mkdocstrings_handlers/python/handler.py", line 195, in collect
    unresolved, iterations = loader.resolve_aliases(only_exported=True, only_known_modules=True)
  File "/home/kaan/.local/lib/python3.10/site-packages/griffe/loader.py", line 179, in resolve_aliases
    self.expand_wildcards(wildcards_module)
  File "/home/kaan/.local/lib/python3.10/site-packages/griffe/loader.py", line 254, in expand_wildcards
    self.expand_wildcards(member, only_known_modules, seen)  # type: ignore[arg-type]
  File "/home/kaan/.local/lib/python3.10/site-packages/griffe/loader.py", line 260, in expand_wildcards
    if new_member.name not in obj.members or obj[new_member.name].lineno < alias_lineno:
TypeError: '<' not supported between instances of 'NoneType' and 'int'

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Comments: 19 (9 by maintainers)

Commits related to this issue

Most upvoted comments

Thank you for testing the new handler then πŸ˜„ It helps improving it πŸ™‚

+1
pawamoy on Jun 3, 2022

In the repository, my ci.yml uses older version to avoid any trouble for now.

+1
kaanaksit on Jun 3, 2022

Sure, it is located here: https://github.com/kunguz/odak

Very kind of you to offer this kind of help!

+1
kaanaksit on Jun 3, 2022

Yeah there are some delays here and there. Just try again, it’ll catch up eventually πŸ™‚ EDIT: ah, it’s Griffe that was updated, not mkdocstrings itself. https://pypi.org/project/griffe/ Your mkdocstrings dependency spec should stay the same (0.19) πŸ˜„ Sorry for the confusion πŸ™‚

+1
pawamoy on Jun 3, 2022

0.20.0 available on PyPI πŸ˜„ If you didn’t set upper bounds on Griffe, you can just restart your pipeline and it should work πŸ™‚ Let me know if you still encounter errors! Closing.

+1
pawamoy on Jun 3, 2022

Wow that escalated quickly πŸ˜„ Thank you for being proactive. I guess at this point, I have to wait until a new pip version is available for my build script than migrate to the new one?

+1
kaanaksit on Jun 3, 2022

Already fixed πŸ˜‚ Going to push a release now πŸ™‚ Thank you for offering to help!

+1
pawamoy on Jun 3, 2022

Thank you for your fast response! Is it then because this new handler treats comments differently or needs a different kind of comment type in order to function properly? Just trying to understand the case a little bit better.

+1
kaanaksit on Jun 3, 2022

What changed is that previously you were using the legacy Python handler, and now you are using the new handler. More info here: https://mkdocstrings.github.io/handlers/overview/#about-the-python-handlers

This issue was reported in the Griffe repo as well, I’m working on a fix πŸ™‚

+1
pawamoy on Jun 3, 2022
Read more comments on GitHub
← mkdocstrings: Circular dependency with `mkdocstrings-python-legacy`
mkdocstrings: jinja2.exceptions.TemplateNotFound: alias.html →