Does not parse citations in docstrings using mkdocstrings about mkdocs-bibtex

[shyamd]

Thanks @pawamoy for the explanation. Unfortunately, i'm already maintaining this plugin on fumes, so I don't have the time to make a markdown extension. Happy to deprecate this if someone does and it works as an effective replacement.

[pawamoy]

There possibly is another way: if you look at this comment, you'll see that there's a way to allow the mkdocs-macros-plugin to work on docstrings. There might be similar hacks possible for other plugins 😄

[pawamoy]

mkdocstrings maintainer here 👋

The short explanation is that MkDocs plugins never get to see (and work on) docstrings. Everything happens in the Markdown to HTML process. Plugins that define the on_page_markdown only get to see the mkdocstrings instructions (::: stuff).

To make this work, one solution, if feasible, is to rewrite the plugin as a Markdown extension. mkdocstrings reuses all configured Markdown extensions when converting docstrings.

[kvanderwijst]

Thanks for the explanation, good to know!

[fralau]

Here is indeed a use case similar to the question asked about the Mkdocs-Macros plugin (I am the author of that plugin).

Perhaps it's best that I quote directly @pawamoy's relevant passage about this in mkdocstrings/mkdocstrings#615:

This has been discussed several times already (...): it's not possible without hacks. mkdocs-macros and mkdocstrings work at different levels: mkdocs-macros at the plugin level (in something like the on_page_markdown hook) while mkdocstrings renders docstrings at the Markdown conversion level, so in-between on_page_markdown and on_page_content. That means mkdocs-macros never sees the docstrings.

This explains accurately the phenomenon that happens to mkdocs-bibtex. Adapting snippet to your needs should do it.

If my understanding is correct you might have to refactor your on_page_markdown() method, so as to put together the 5 calls in a separate render() method, which you could then reference?

mkdocs-bibtex/src/mkdocs_bibtex/plugin.py

Lines 121 to 177 in 728a65a

	def on_page_markdown(self, markdown, page, config, files):
	"""
	Parses the markdown for each page, extracting the bibtex references
	If a local reference list is requested, this will render that list where requested
	1. Finds all cite keys (may include multiple citation references)
	2. Convert all cite keys to citation quads:
	(full cite key,
	individual cite key,
	citation key in corresponding style,
	citation for individual cite key)
	3. Insert formatted cite keys into text
	4. Insert the bibliography into the markdown
	5. Insert the full bibliograph into the markdown
	"""
	# 1. Grab all the cited keys in the markdown
	cite_keys = find_cite_blocks(markdown)
	# 2. Convert all the citations to text references
	citation_quads = self.format_citations(cite_keys)
	# 3. Convert cited keys to citation,
	# or a footnote reference if inline_cite is false.
	if self.cite_inline:
	markdown = insert_citation_keys(
	citation_quads,
	markdown,
	self.csl_file,
	self.bib_data_bibtex,
	)
	else:
	markdown = insert_citation_keys(citation_quads, markdown)
	# 4. Insert in the bibliopgrahy text into the markdown
	bib_command = self.config.get("bib_command", "\\bibliography")
	if self.config.get("bib_by_default"):
	markdown += f"\n{bib_command}"
	bibliography = format_bibliography(citation_quads)
	markdown = re.sub(
	re.escape(bib_command),
	bibliography,
	markdown,
	)
	# 5. Build the full Bibliography and insert into the text
	full_bib_command = self.config.get("full_bib_command", "\\full_bibliography")
	markdown = re.sub(
	re.escape(full_bib_command),
	self.full_bibliography,
	markdown,
	)
	return markdown