MkDocs plugin to generate reference Markdown pages
Project description
MkRefs
The MkRefs plugin
for MkDocs
generates reference Markdown pages from a knowledge graph,
based on the kglab
project.
No graph database is required; however, let us know if you'd like to use one in particular.
There are several planned use cases for the MkRefs plugin, including:
- biblio – semantic bibliography entries, generated from RDF
- glossary – semantic glossary entries, generated from RDF
- apidocs – semantic apidocs supporting the Diátaxis grammar for documentation, generated as RDF from Python source code
- depend – semantic dependency graph for Python libraries, generated as RDF from
setup.py
- index – semantic search index, generated as RDF from MkDocs content
Only the biblio component has been added to MkRefs so far, although these other components exist in other projects and are being integrated.
Why does this matter?
A key takeaway is that many software engineering aspects of open source projects involve graphs, therefore a knowledge graph can provide an integral part of an open source repository. Moreover, by using semantic representation (RDF) projects that integrate with each other can share (i.e., federate) common resources, for example to share definitions, analyze mutual dependencies, etc.
Installation
To install the plugin using pip
:
python3 -m pip install mkrefs
Then add the plugin into the mkdocs.yml
file:
plugins:
- mkrefs
In addition, the following configuration parameter is expected:
mkrefs_config
- YAML configuration file for MkRefs; e.g.,mkrefs.yml
Bibliography
A biblio
parameter within the configuration file expects four
required sub-parameters:
graph
– an RDF graph represented as a Turtle (TTL) file, e.g.,mkrefs.ttl
page
– name of the generated Markdown page, e.g.,biblio.md
template
– a Jinja2 template to generate Markdown, e.g.,biblio.jinja
queries
– SPARQL queries used to extract bibliography data from the knowledge graph
See the mkrefs.ttl
file for an example bibliography represented in RDF.
This comes from the documentation for the pytextrank
open source project.
In the example RDF, the bibo vocabulary represents bibliographic citations, and the FOAF vocabulary represents authors. This also uses two custom OWL relations from the derwen vocabulary:
derw:citeKey
– citekey used to identify a bibliography entry within the documentationderw:openAccess
– open access URL for a bibliography entry (if any)
The queries
parameter has three required SPARQL queries:
entry
– to select the identifiers for all of the bibliograpy entriesentry_author
– a mapping to identify author links for each bibliography entryentry_publisher
- the publisher link for each bibliography entry (if any)
Note that the named of the generated Markdown page for the
bibliography must appear in the nav
section of your mkdocs.yml
configuration file.
See the structure used in this repo for an example.
You may use any valid RDF representation for a bibliography. Just be sure to change the three SPARQL queries and the Jinja2 template accordingly.
While this example uses an adaptation of the MLA Citation Style, feel free to modify the Jinja2 template to generate whatever bibliographic style you need.
Let us know if you need features to parse and generate BibTeX.
Best Practices
Where possible, the bibliography entries should use the conventions at https://www.bibsonomy.org/ for their citation keys.
Journal abbreviations should use ISO 4 standards, for example from https://academic-accelerator.com/Journal-Abbreviation/System
Links to online versions of cited works should use DOI for persistent identifiers.
When available, open access URLs should be listed as well.
Usage
The standard way to generate documentation with MkDocs is:
mkdocs build
However, there's also a command line entry point provided:
mkrefs biblio docs/mkrefs.yml
If you'd prefer to generate a bibliography programmatically within
Python scripts, see the code for usage of the MkRefsPlugin
class,
plus two utility functions:
load_kg()
render_biblio()
What is going on here?
When the plugin runs,
- It parses its configuration file to identify the target Markdown page to generate and the Jinja2 template
- The plugin also loads an RDF graph from the indicated TTL file
- Three SPARQL queries are run to identify the unique entities to extract from the graph
- The graph is serialized as JSON-LD
- The
author
,publisher
, and bibliographyentry
entities are used to denormalize the graph into a JSON data object - The JSON is rendered using the Jinja2 template to generate the Markdown
- The Markdown page is parsed and rendered by MkDocs as HTML, etc.
Caveats
While the MkDocs
utility is astoundingly useful,
its documentation (and coding style) leave much room for improvement.
The documentation for developing plugins
is not even close to what happens when its code executes.
Consequently, the MkRefs project is an attempt to reverse-engineer the code from many other MkDocs plugins, while documenting its observed event sequence, required parameters, limitations and workarounds, etc.
Two issues persist, where you will see warnings even though the MkRefs code is handling configuration as recommended:
WARNING - Config value: 'mkrefs_config'. Warning: Unrecognised configuration name: mkrefs_config
and
INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
- biblio.md
For now, you can simply ignore both of these warnings. Meanwhile, we'll work on eliminating them.
License and Copyright
Source code for MkRefs plus its logo, documentation, and examples have an MIT license which is succinct and simplifies use in commercial applications.
All materials herein are Copyright © 2021 Derwen, Inc.
Acknowledgements
This plugin code is based on the marvelous examples in https://github.com/byrnereese/mkdocs-plugin-template with kudos to @byrnereese, and also many thanks to @louisguitton, @dmccreary, and @LarrySwanson for their inspiration and insights.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.