Skip to content

Add ability to attach citations in docstrings and markdown pages#12

Draft
patcon wants to merge 3 commits intomainfrom
bibtex-citations
Draft

Add ability to attach citations in docstrings and markdown pages#12
patcon wants to merge 3 commits intomainfrom
bibtex-citations

Conversation

@patcon
Copy link
Copy Markdown
Owner

@patcon patcon commented Dec 31, 2025

scanpy is very rigourous in that many of it's methods and recipes cite scholarly sources. For example:
https://scanpy.readthedocs.io/en/stable/api/preprocessing.html

It would nice to try to do the same, to set ourselves off on the right foot.

The documentation tool we're using (mkdocs and mkdocs-material) doesn't have as much selection for extensions to help with citations. The only available plugin is no longer maintained, but I gave it a shot anyhow:
https://github.com/shyamd/mkdocs-bibtex

What this does so far:

  • enables footnotes and footnotes tooltips
  • added some basic bibtex citations in a docs/references.bib file
  • add an example inline citation on the scanpy API page
  • allows a bibliography to be embedded at the bottom of every page using footnotes (required for JS to work)
  • add custom css to hide the bibliography on most every page, so only the tooltip displays (the footnotes are required). the only page the footnotes aren't hidden on is the references.md page
  • add the full bibliography page in the nav

@patcon patcon marked this pull request as draft December 31, 2025 06:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant