mkdocs-webis 0.1.2__tar.gz → 0.1.3__tar.gz

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-webis
-Version: 0.1.2
+Version: 0.1.3
 Summary: Webis style and BibTeX citations for MkDocs Material.
 Author-email: Jan Heinrich Merker <heinrich.merker@uni-jena.de>
 License-Expression: MIT
@@ -86,6 +86,7 @@ Some studies use axioms for re-ranking [@hagen2016axiomatic, @bondarenko2022axio
 Citations are rendered as gray author–year links in brackets (e.g., "[Fang et al., 2004]" or "[Hagen et al., 2016; Bondarenko et al., 2022]"), like on the Webis slides.
 They link to a "References" section at the bottom of the same page, which lists all references cited on that page.
 Multiple keys are separated by commas or semicolons.
+Citations also work in API docstrings rendered by [mkdocstrings](https://mkdocstrings.github.io/).
 
 We recommend copying BibTeX entries from [DBLP](https://dblp.org/).
 

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/README.md

@@ -54,6 +54,7 @@ Some studies use axioms for re-ranking [@hagen2016axiomatic, @bondarenko2022axio
 Citations are rendered as gray author–year links in brackets (e.g., "[Fang et al., 2004]" or "[Hagen et al., 2016; Bondarenko et al., 2022]"), like on the Webis slides.
 They link to a "References" section at the bottom of the same page, which lists all references cited on that page.
 Multiple keys are separated by commas or semicolons.
+Citations also work in API docstrings rendered by [mkdocstrings](https://mkdocstrings.github.io/).
 
 We recommend copying BibTeX entries from [DBLP](https://dblp.org/).
 

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/docs/citations.md

@@ -22,6 +22,7 @@ A journal article looks like this: [@fang2011diagnostic].
 
 - Separate multiple keys by commas (semicolons work, too).
 - Citations inside inline code or code blocks are not replaced, as in the example above.
+- Citations in content that other plugins insert while rendering a page (e.g., API docstrings from [mkdocstrings](https://mkdocstrings.github.io/)) are replaced, too, and their references are added to the "References" section.
 - Unknown keys and invalid BibTeX files fail the build.
 - LaTeX markup in the BibTeX fields (e.g., `{\"{o}}` for "ö") is converted to plain text.
 

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/mkdocs_webis/bibliography.py

@@ -5,13 +5,15 @@ Citations from a BibTeX file.
   e.g., "[Fang et al., 2004]".
 - Each page that cites at least one reference gets a references section at the
   bottom, listing the cited references, including the BibTeX of each entry.
+- Citations that only appear in the rendered HTML (e.g., from docstrings
+  inserted by mkdocstrings) are replaced as well, and their references are added.
 """
 
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 from html import escape
 from pathlib import Path
-from re import DOTALL, MULTILINE, Match, compile as re_compile
+from re import DOTALL, MULTILINE, Match, Pattern, compile as re_compile
 from typing import Final
 
 from bibtexparser.entrypoint import parse_string
@@ -26,6 +28,8 @@ _PATTERN_CITATION_SEPARATOR: Final = re_compile(r"\s*[,;]\s*")
 _PATTERN_CODE: Final = re_compile(
     r"(^[ \t]*```.*?^[ \t]*```|`[^`\n]+`)", MULTILINE | DOTALL
 )
+# Code blocks and inline code in HTML, in which citations are not replaced.
+_PATTERN_CODE_HTML: Final = re_compile(r"(<pre\b.*?</pre>|<code\b.*?</code>)", DOTALL)
 # Fields that are not LaTeX (where, e.g., "%" is not a comment).
 _VERBATIM_FIELDS: Final = frozenset({"url", "doi", "eprint"})
 
@@ -239,16 +243,20 @@ class Bibliography:
         blocks.extend(self.render_reference(entry) for entry in entries)
         return "\n\n".join(blocks) + "\n"
 
-    def process(self, markdown: str) -> str:
-        """Replace citations and append the references section, if any."""
+    def _replace_citations(self, text: str, code_pattern: Pattern[str]) -> str:
+        """Replace citations outside of code and remember the cited keys."""
         self._cited_keys = set()
         # Odd indices of the split are code, which is kept as is.
-        markdown = "".join(
+        return "".join(
             part
             if index % 2 == 1
             else _PATTERN_CITATION.sub(self._replace_citation, part)
-            for index, part in enumerate(_PATTERN_CODE.split(markdown))
+            for index, part in enumerate(code_pattern.split(text))
         )
+
+    def process(self, markdown: str) -> str:
+        """Replace citations and append the references section, if any."""
+        markdown = self._replace_citations(markdown, _PATTERN_CODE)
         if self._cited_keys:
             markdown = (
                 markdown.rstrip()
@@ -256,3 +264,25 @@ class Bibliography:
                 + self.render_references(self._cited_keys)
             )
         return markdown
+
+    def process_html(self, html: str) -> str:
+        """
+        Replace citations that remain in the rendered HTML of a page (e.g., from
+        docstrings) and append their references, unless already listed.
+        """
+        html = self._replace_citations(html, _PATTERN_CODE_HTML)
+        missing = [
+            self.entries[key]
+            for key in self._cited_keys
+            if f'<div class="reference" id="{escape(key)}">' not in html
+        ]
+        if not missing:
+            return html
+        blocks = [html.rstrip()]
+        if 'id="references"' not in html:
+            blocks.append('<h2 id="references">References</h2>')
+        blocks.extend(
+            self.render_reference(entry)
+            for entry in sorted(missing, key=lambda e: e.sort_key)
+        )
+        return "\n".join(blocks) + "\n"

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/mkdocs_webis/plugin.py

@@ -115,6 +115,18 @@ class WebisPlugin(BasePlugin[WebisPluginConfig]):
         except BibliographyError as error:
             raise PluginError(f"{error} (in {page.file.src_uri})") from error
 
+    def on_page_content(
+        self, html: str, /, *, page: Page, config: MkDocsConfig, files: Files
+    ) -> str | None:
+        # Citations from content that other plugins insert while rendering the
+        # Markdown (e.g., docstrings from mkdocstrings).
+        if self._bibliography is None:
+            return html
+        try:
+            return self._bibliography.process_html(html)
+        except BibliographyError as error:
+            raise PluginError(f"{error} (in {page.file.src_uri})") from error
+
 
 def files_resource(name: str) -> Traversable:
     return files("mkdocs_webis").joinpath("assets", name)

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/mkdocs_webis.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-webis
-Version: 0.1.2
+Version: 0.1.3
 Summary: Webis style and BibTeX citations for MkDocs Material.
 Author-email: Jan Heinrich Merker <heinrich.merker@uni-jena.de>
 License-Expression: MIT
@@ -86,6 +86,7 @@ Some studies use axioms for re-ranking [@hagen2016axiomatic, @bondarenko2022axio
 Citations are rendered as gray author–year links in brackets (e.g., "[Fang et al., 2004]" or "[Hagen et al., 2016; Bondarenko et al., 2022]"), like on the Webis slides.
 They link to a "References" section at the bottom of the same page, which lists all references cited on that page.
 Multiple keys are separated by commas or semicolons.
+Citations also work in API docstrings rendered by [mkdocstrings](https://mkdocstrings.github.io/).
 
 We recommend copying BibTeX entries from [DBLP](https://dblp.org/).
 

mkdocs_webis-0.1.3/mkdocs_webis.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.3",
+  "distance": 0,
+  "node": "g4156484d3dff0dbb4a969668f46252cf27f66139",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-20"
+}

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/tests/test_bibliography.py

@@ -149,3 +149,30 @@ def test_process_unknown_key() -> None:
     bibliography = Bibliography(entries=parse_bibtex(BIBTEX))
     with raises(BibliographyError):
         bibliography.process("See [@unknown].")
+
+
+def test_process_html_citations() -> None:
+    bibliography = Bibliography(entries=parse_bibtex(BIBTEX))
+    html = bibliography.process_html("<p>See [@lv2011lower; @fang2004formal].</p>")
+    assert '<a href="#fang2004formal">Fang et al., 2004</a>' in html
+    assert '<h2 id="references">References</h2>' in html
+    # Sorted by first author.
+    assert html.index('id="fang2004formal"') < html.index('id="lv2011lower"')
+
+
+def test_process_html_adds_missing_references() -> None:
+    bibliography = Bibliography(entries=parse_bibtex(BIBTEX))
+    html = bibliography.process_html(
+        "<p>See [@fang2004formal, @lv2011lower].</p>\n"
+        '<h2 id="references">References</h2>\n'
+        '<div class="reference" id="fang2004formal">...</div>'
+    )
+    assert html.count('id="references"') == 1
+    assert html.count('id="fang2004formal"') == 1
+    assert '<div class="reference" id="lv2011lower">' in html
+
+
+def test_process_html_ignores_code() -> None:
+    bibliography = Bibliography(entries=parse_bibtex(BIBTEX))
+    html = "<p>Use <code>[@key]</code> to cite.</p>\n<pre><code>[@unknown]\n</code></pre>"
+    assert bibliography.process_html(html) == html

{mkdocs_webis-0.1.2 → mkdocs_webis-0.1.3}/tests/test_plugin.py

@@ -115,3 +115,22 @@ def test_unknown_citation(tmp_path: Path) -> None:
 def test_missing_bibliography(tmp_path: Path) -> None:
     with raises((PluginError, Abort)):
         _build(tmp_path, ":\n      bibliography: missing.bib")
+
+
+def test_citations_in_rendered_html(tmp_path: Path) -> None:
+    # Simulate content inserted while rendering the Markdown (e.g., docstrings).
+    (tmp_path / "hooks.py").write_text(
+        "def on_page_markdown(markdown, **kwargs):\n"
+        "    return markdown.replace('DOCSTRING', '<p>[@doe2020test]</p>')\n"
+    )
+    site_dir = _build(
+        tmp_path,
+        ":\n      bibliography: references.bib",
+        page="# Home\n\nDOCSTRING\n",
+        extra_config="hooks:\n  - hooks.py\n",
+    )
+    html = (site_dir / "index.html").read_text()
+    assert "[@doe2020test]" not in html
+    assert '&#91;<a href="#doe2020test">Doe, 2020</a>&#93;' in html
+    assert '<h2 id="references">References</h2>' in html
+    assert '<div class="reference" id="doe2020test">' in html

mkdocs_webis-0.1.2/mkdocs_webis.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.1.2",
-  "distance": 0,
-  "node": "g9ab792225cf6fd2f9fb30db024df95bce7b5a118",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-16"
-}