Skip to content

Commit cefdac8

Browse files
cetericeteri
committed
prepare release
1 parent 85841f3 commit cefdac8

File tree

5 files changed

+107
-23
lines changed

5 files changed

+107
-23
lines changed

‎README.md

+95-21
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,128 @@
1-
# mkrefs
1+
# MkRefs
22

3-
MkDocs plugin to generate reference Markdown pages from a knowledge
4-
graph, leveraging
5-
[`kglab`](https://github.com/DerwenAI/kglab).
3+
The **MkRefs** [plugin](http://www.mkdocs.org/user-guide/plugins/)
4+
for [`MkDocs`](https://www.mkdocs.org/)
5+
generates reference Markdown pages from a knowledge graph,
6+
based on the [`kglab`](https://github.com/DerwenAI/kglab) project.
67

7-
This plugin code is based on the marvelous examples in
8-
<https://github.com/byrnereese/mkdocs-plugin-template>
9-
with kudos to [@byrnereese](https://github.com/byrnereese/)
8+
No graph database is required; however, let us know if you'd like to
9+
use one in particular.
10+
11+
There are several planned use cases for the **MkRefs** plugin,
12+
including:
13+
14+
* *biblio* – semantic bibliography entries, generated from RDF
15+
* *glossary* – semantic glossary entries, generated from RDF
16+
* *apidocs* – semantic [*apidocs*](https://pypi.org/search/?q=apidocs) supporting the [Diátaxis](https://derwen.ai/docs/kgl/learn/#a-grammar-of-learning) grammar for documentation, generated as RDF from Python source code
17+
* *depend* – semantic dependency graph for Python libraries, generated as RDF from `setup.py`
18+
* *index* – semantic search index, generated as RDF from MkDocs content
19+
20+
Only the *biblio* component has been added to **MkRefs** so far,
21+
although these other components exist in other projects and are being
22+
integrated.
23+
24+
A key takeaway is that many software engineering aspects of open
25+
source projects involve graphs, therefore a knowledge graph can
26+
provide an integral part of an open source repository.
27+
Moreover, by using semantic representation (RDF) projects that
28+
integrate with each other can share (i.e., federate) common resources,
29+
for example to share definitions, analyze mutual dependencies, etc.
1030

1131

12-
## Setup
32+
## Installation
1333

14-
To install the plugin using pip:
34+
To install the plugin using `pip`:
1535

1636
```
17-
pip install mkrefs
37+
python3 -m pip install mkrefs
1838
```
1939

20-
Then activate the plugin in `mkdocs.yml`:
40+
Then add the plugin into the `mkdocs.yml` file:
2141
```yaml
2242
plugins:
2343
- mkrefs
2444
```
45+
In addition, the following configuration parameter is expected:
46+
47+
* `mkrefs_config` - YAML configuration file for **MkRefs**; e.g., `mkrefs.yml`
48+
49+
50+
## Bibliography
51+
52+
A `biblio` parameter within the configuration file expects four
53+
required sub-parameters:
54+
55+
* `graph` – an RDF graph represented as a Turtle (TTL) file, e.g., `mkrefs.ttl`
56+
* `page` – name of the generated Markdown page, e.g., `biblio.md`
57+
* `template` – a Jinja2 template to generate the Markdown, e.g., `biblio.jinja`
58+
* `queries` – SPARQL queries used to extract bibliography data from the knowledge graph
59+
60+
See the [`mkrefs.ttl`](https://github.com/DerwenAI/mkrefs/blob/main/docs/mkrefs.ttl)
61+
file for an example bibliography represented in RDF.
62+
This comes from the documentation for the [`pytextrank`](https://derwen.ai/docs/ptr/biblio/)
63+
open source project.
2564

65+
In the example RDF, the [*bibo*](http://bibliontology.com/) vocabulary represents
66+
bibliographic citations, and the [*FOAF*](http://xmlns.com/foaf/spec/) vocabulary
67+
represents authors.
68+
This also uses two custom OWL relations from the [*derwen*](https://derwen.ai/ns/v1)
69+
vocabulary:
2670

27-
## Configuration
71+
* `derw:citeKey` – citekey used to identify a bibliography entry within the documentation
72+
* `derw:openAccess` – open access URL for a bibliography entry (if any)
2873

29-
The following parameters are expected:
74+
The `queries` parameter has three required SPARQL queries:
3075

31-
* `mkrefs_config` - YAML configuration file for MkRefs; defaults to `mkrefs.yml`
76+
* `entry` – to select the identifiers for all of the bibliograpy entries
77+
* `entry_author` – a mapping to indentify author links for each bibliography entry
78+
* `entry_publisher` - the publisher link for each bibliography entry (if any)
79+
80+
Note that the named of the generated Markdown page for the
81+
bibliography must appear in the `nav` section of your `mkdocs.yml`
82+
configuration file.
83+
See the structure used in this repo for an example.
84+
85+
You may use any valid RDF representation for a bibliography.
86+
Just be sure to change the three SPARQL queries and the Jinja2
87+
template accordingly.
3288

3389

3490
## Usage
3591

92+
The standard way to generate documentation with MkDocs is:
3693
```
37-
mkrefs biblio docs/mkrefs.yml
94+
mkdocs build
3895
```
3996

97+
However, there's also a command line *entry point* provided:
98+
```
99+
mkrefs biblio docs/mkrefs.yml
100+
```
40101

41-
## See Also
102+
If you'd prefer to generate a bibliography programmatically within
103+
Python scripts, see the code for usage of the `MkRefsPlugin` class,
104+
plus two utility functions:
42105

43-
[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/
44-
[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables
45-
[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
106+
* `load_kg()`
107+
* `render_biblio()`
46108

47109

48110
## License and Copyright
49111

50-
Source code for **mkrefs** plus its logo, documentation, and examples
112+
Source code for **MkRefs** plus its logo, documentation, and examples
51113
have an [MIT license](https://spdx.org/licenses/MIT.html) which is
52114
succinct and simplifies use in commercial applications.
53115

54-
All materials herein are Copyright &copy; 2020-2021 Derwen, Inc.
116+
All materials herein are Copyright &copy; 2021 Derwen, Inc.
117+
118+
119+
## Acknowledgements
120+
121+
This plugin code is based on the marvelous examples in
122+
<https://github.com/byrnereese/mkdocs-plugin-template>
123+
with kudos to [@byrnereese](https://github.com/byrnereese/)
124+
and also many thanks to
125+
[@louisguitton](https://github.com/louisguitton)
126+
and
127+
[@dmccreary](https://github.com/dmccreary)
128+
for their inspiration and insights.

‎bin/push_pypi.sh

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#!/bin/bash -e
2+
3+
## debugging the uploaded README:
4+
# pandoc README.md --from markdown --to rst -s -o README.rst
5+
6+
rm -rf dist
7+
python setup.py sdist bdist_wheel
8+
twine upload --verbose dist/*

‎changelog.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22

33
## 0.1.0
44

5-
2021-05-??
5+
2021-05-22
66

77
* initial release

‎mkrefs/__init__.py

+2
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
from .plugin import MkRefsPlugin
66

7+
from .biblio import load_kg, render_biblio
8+
79
from .cli import cli
810

911
from .version import __version__

‎requirements.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
Jinja2 >= 2.10.3
22
PyYAML >= 5.1
3-
kglab >= 0.4
3+
#kglab >= 0.4
44
livereload >= 2.6.1
55
mkdocs >= 1.0.4
66
typer >= 0.3.2

0 commit comments

Comments
 (0)