Skip to content

[bug] Admonition processing and mkdocstrings #69

@wfondrie

Description

@wfondrie

Currently (v0.6.0), admonition processing causes a error when interacting with markdown files intended to be processed with mkdocstrings.

Here is an MRE using uv:

#!/usr/bin/env bash

uv init --package foo
cd foo
uv add mkdocs 'mkdocstrings[python]' 'mkquartodocs==0.6.0'
uv run mkdocs new .
touch docs/bar.qmd

# Add a Python function:
cat > src/foo/main.py << EOL
def greet(name: str) -> str:
    """Return a greeting message.

    Args:
        name (str): The name of the person to greet.

    Returns:
        str: A greeting message.
    """
    return f"Hello, {name}!"
EOL

# Add config
cat >> mkdocs.yml << EOL
plugins:
  - mkquartodocs:
      ignore_pattern: "docs/index.md"
  - mkdocstrings:
      default_handler: python
EOL

# Add an mkdocstrings admonition to index.md
echo "::: foo.main.hello" >> docs/index.md

# Build the docs
uv run mkdocs build

This results in the following error:

INFO    -  mkquartodocs: Updating directory context
INFO    -  mkquartodocs: [PosixPath('/Users/wfondrie/scratch/reprex/foo/docs/bar.md')]
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/wfondrie/scratch/reprex/foo/site
INFO    -  mkquartodocs: Running <mkquartodocs.extension.AdmotionCellDataPreprocessor
           object at 0x103f4c910>
ERROR   -  Error reading page 'index.md': Cell data contains admonition: [':::
           foo.main.hello']
Traceback (most recent call last):
  File "/Users/wfondrie/scratch/reprex/foo/.venv/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
             ^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/click/core.py", line 1462, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/click/core.py", line 1383, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/click/core.py", line 1850, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/click/core.py", line 1246, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/click/core.py", line 814, in invoke
    return callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/mkdocs/__main__.py", line 288, in build_command
    build.build(cfg, dirty=not clean)
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/mkdocs/commands/build.py", line 310, in build
    _populate_page(file.page, config, files, dirty)
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/mkdocs/commands/build.py", line 167, in _populate_page
    page.render(config, files)
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/mkdocs/structure/pages.py", line 285, in render
    self.content = md.convert(self.markdown)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/markdown/core.py", line 354, in convert
    self.lines = prep.run(self.lines)
                 ^^^^^^^^^^^^^^^^^^^^
  File "/Users/wfondrie/scratch/reprex/foo/.venv/lib/python3.11/site-packages/mkquartodocs/extension.py", line 442, in run
    raise ValueError(f"Cell data contains admonition: {bads}")
ValueError: Cell data contains admonition: ['::: foo.main.hello']

I think the change that needs to happen is just making the ignore_pattern apply to admonition processing as well.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions