Incompatibility of mkdocstrings (or handler?) with pymdownx.snippets: auto_append: (python 3.7)

[Enn83]

Hi!
First of all, I must say that I'm still using Python 3.7, and thus I'm using an "old" version of mkdocs, mkdocstrings, etc., so this bug may be already solved or is no longer relevant. (An upgrade to python 3.11 is planned for this year, ASAP 🤞...)

Here is my Pipfile:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
markdown-exec = {version = "==1.6.0", extras = ["ansi"]}
mkdocs = "==1.5.2"
mkdocs-material = "==9.2.3"
mkdocs-material-extensions = "==1.1.1"
mkdocs-literate-nav = "==0.6.0"
mkdocs-gen-files = "==0.5.0"
mkdocstrings = "==0.22" 
mkdocstrings-python = "==1.1.2" # More need python >= 3.8

[requires]
python_version = "3.7"

So when I add this markdown extension:

markdown_extensions:
  - pymdownx.snippets:
      auto_append:
        - includes/abreviations.md

And then I browse my site (build or serve), all admonitions in the generated pages looks like this:

It seems to be because the title contain an <p>...</p> html tag that contain the admonition title, instead of the title itself.

And without the pymdownx.snippets: auto_append: markdown extension, the html looks like this (no <p> html tag):

[pawamoy]

That could make sense: when converting admonition titles from Markdown to HTML, we strip the surrounding <p> tag, but only if it's the only tag at the root level. The auto-append extension appends references at the end of every Markdown string that is converted, therefore we now have more than just a <p> tag, and it isn't stripped, resulting in extra visual space around the admonition title.

But I'd have to confirm: I'm not sure how the references block is rendered (what's it's HTML). I would have thought it would simply not be rendered because unused.

If confirmed, the solution would be to disable auto-append for admonition titles, or somehow improve the stripping.

[pawamoy]

Could you share your docstring please? The one with "Details supplementaires ...".

[pawamoy]

I've tried many things but cannot replicate, so I suppose it's fixed by more recent versions 🤷

With this MkDocs config:

- pymdownx.snippets:
    auto_append: [docs/refs.md]
    base_path: [!relative $config_dir]
    check_paths: true

The contents of refs.md:

[hello]: https://example.com

And this docstring:

    self.aliases: dict[str, Alias] = {}
    """The aliases pointing to this object.

    Note: Additional details on parameter `thing`
        Testing admonitions.
    """

I get the following HTML:

<details class="note" open="">
  <summary>Additional details on parameter <code>thing</code></summary>
  <p>Testing admonitions.</p>
</details>

[pawamoy]

In the meantime you can probably fix the spacing with CSS, though it could be hard to select just the right paragraphs.

[Enn83]

Thanks for your help and indications!

Solution

... we strip the surrounding <p> tag, but only if it's the only tag at the root level. The auto-append extension appends references at the end of every Markdown string that is converted ...

As I read this, I remembered that I had added Markdown/html comments in the auto_append: abreviations.md file. After removing them and any other content except abbreviations in the abbreviations.md file, the admonitions were fixed and now looks OK!

---

Could you share your docstring please? The one with "Details supplementaires ...".

My docstring was:

    def func(self, ...):
        """
        ...

        Note: Détails supplémentaires sur le paramètre `xxxxx`
            Ce paramètre est pris en compte si ...
        """
        pass

My abbreviations.md abbreviations file was:

<!-- LICENSES -->
*[BSD]: Berkeley Source Distribution
*[PSF]: Python Software Foundation
*[MIT]: Massachusetts Institute of Technology
*[MPL]: Public License Mozilla
*[EPL]: Public License Eclipse
*[GPL]: GNU General Public License
*[LGPL]: GNU Lesser General Public License
*[AGPL]: GNU Affero General Public License

Here, the first line (comment) was the cause of the problem...

The generated HTML was:

[pawamoy]

I see, thanks for reporting back! That will be super helpful if someone else has the same issue 🙂 I didn't think of HTML comments in the snippet 😅