Skip to content

Commit 0ba8cfb

Browse files
committed
WIP apidocs
1 parent c994687 commit 0ba8cfb

File tree

8 files changed

+102
-28
lines changed

8 files changed

+102
-28
lines changed

README.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ including:
1717
* *depend* – semantic dependency graph for Python libraries, generated as RDF from `setup.py`
1818
* *index* – semantic search index, generated as RDF from MkDocs content
1919

20-
Only the *biblio* and *glossary* components has been added to
21-
**MkRefs** so far, although these other mentioned components exist in
22-
separate projects and are being integrated.
20+
Only the *apidocs*, *biblio*, and *glossary* components have been
21+
added to **MkRefs** so far, although the other mentioned components
22+
exist in separate projects and are being integrated.
2323

2424

2525
## Why does this matter?
@@ -171,13 +171,15 @@ Python scripts, see the code for usage of the `MkRefsPlugin` class,
171171
plus some utility functions:
172172

173173
* `load_kg()`
174+
* `render_apidocs()`
174175
* `render_biblio()`
175176
* `render_glossary()`
176177

177178
There are also command line *entry points* provided, which can be
178179
helpful during dev/test cycles on the semantic representation of your
179180
content:
180181
```
182+
mkrefs apidocs docs/mkrefs.yml
181183
mkrefs biblio docs/mkrefs.yml
182184
mkrefs glossary docs/mkrefs.yml
183185
```

docs/biblio.jinja

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ URLs are listed as well.
2222

2323
["{{ item.title }}"]({{ item.id }})
2424
{% for auth in item.authorList %}{% if loop.index > 1 %}, {% endif %}[**{{ auth.name }}**]({{ auth.id }}){% endfor %}
25-
{% if item.isPartOf %}[*{{ item.isPartOf[0].shortTitle }}*]({{ item.isPartOf[0].identifier.id }}){% if item.volume %} **{{ item.volume.value }}**{% endif %}{% if item.issue %} {{ item.issue.value }}{% endif %}{% if item.pageStart %} pp. {{ item.pageStart.value }}-{{ item.pageEnd.value }}{% endif %} {% endif %}({{ item.date.value }}) {% if item.doi %}
25+
{% if item.isPartOf %}[*{{ item.isPartOf[0].shortTitle }}*]({{ item.isPartOf[0].identifier.id }}){% if item.volume %} **{{ item.volume.value }}**{% endif %}{% if item.issue %} {{ item.issue.value }}{% endif %}{% if item.pageStart %} pp. {{ item.pageStart.value }}-{{ item.pageEnd.value }}{% endif %} {% endif %}({{ item.Date.value }}) {% if item.doi %}
2626
DOI: {{ item.doi.value }} {% endif %}{% if item.openAccess %}
2727
open: <a href="{{ item.openAccess.id }}" target="_blank">{{ item.openAccess.id }}</a> {% endif %}
2828
> {{ item.abstract }}

docs/mkrefs.ttl

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ derw:Topic a skos:Concept ,
124124
a bibo:Proceedings ;
125125
bibo:shortTitle "EMNLP"@en ;
126126
dct:title "Proceedings of the 2004 Conference on Empirical Methods in Natural Language Processing"@en ;
127-
dct:date "2004" ;
127+
dct:Date "2004" ;
128128
dct:identifier <https://www.aclweb.org/anthology/venues/emnlp/> ;
129129
dct:publisher <https://www.aclweb.org/portal/>
130130
.
@@ -151,7 +151,7 @@ derw:Topic a skos:Concept ,
151151
dct:title "PositionRank: An Unsupervised Approach to Keyphrase Extraction from Scholarly Documents"@en ;
152152
dct:isPartOf <urn:issn:0891-2017> ;
153153
dct:language "en" ;
154-
dct:date "2017-07-30" ;
154+
dct:Date "2017-07-30" ;
155155
bibo:pageStart "1105" ;
156156
bibo:pageEnd "1115" ;
157157
bibo:authorList (
@@ -168,7 +168,7 @@ derw:Topic a skos:Concept ,
168168
derw:openAccess <https://www.cs.purdue.edu/homes/dgleich/publications/Gleich%202015%20-%20prbeyond.pdf> ;
169169
dct:title "PageRank Beyond the Web"@en ;
170170
dct:language "en" ;
171-
dct:date "2015-08-06" ;
171+
dct:Date "2015-08-06" ;
172172
dct:isPartOf <urn:issn:0036-1445> ;
173173
bibo:volume "57" ;
174174
bibo:issue "3" ;
@@ -187,7 +187,7 @@ derw:Topic a skos:Concept ,
187187
derw:openAccess <https://www.aclweb.org/anthology/2020.coling-main.144.pdf> ;
188188
dct:title "Biased TextRank: Unsupervised Graph-Based Content Extraction"@en ;
189189
dct:language "en" ;
190-
dct:date "2020-12-08" ;
190+
dct:Date "2020-12-08" ;
191191
dct:isPartOf <urn:issn:1525-2477> ;
192192
bibo:volume "28" ;
193193
bibo:pageStart "1642" ;
@@ -207,7 +207,7 @@ derw:Topic a skos:Concept ,
207207
derw:openAccess <http://ilpubs.stanford.edu:8090/422/1/1999-66.pdf> ;
208208
dct:title "The PageRank Citation Ranking: Bringing Order to the Web"@en ;
209209
dct:language "en" ;
210-
dct:date "1999-11-11" ;
210+
dct:Date "1999-11-11" ;
211211
dct:isPartOf <http://ilpubs.stanford.edu:8090/> ;
212212
bibo:authorList (
213213
<https://derwen.ai/s/mk6xj6cfrrxg>
@@ -224,7 +224,7 @@ derw:Topic a skos:Concept ,
224224
derw:openAccess <https://web.eecs.umich.edu/~mihalcea/papers/mihalcea.emnlp04.pdf> ;
225225
dct:title "TextRank: Bringing Order into Text"@en ;
226226
dct:language "en" ;
227-
dct:date "2004-07-25" ;
227+
dct:Date "2004-07-25" ;
228228
dct:isPartOf <https://www.aclweb.org/anthology/venues/emnlp/> ;
229229
bibo:pageStart "404" ;
230230
bibo:pageEnd "411" ;
@@ -240,7 +240,7 @@ derw:Topic a skos:Concept ,
240240
derw:citeKey "williams2016"@en ;
241241
dct:title "Summarizing documents"@en ;
242242
dct:language "en" ;
243-
dct:date "2016-09-25" ;
243+
dct:Date "2016-09-25" ;
244244
bibo:presentedAt <https://2016.pygotham.org/> ;
245245
bibo:authorList (
246246
<https://derwen.ai/s/2t2mbms2x4p3>

docs/ref.jinja

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,45 @@
1-
# Package Reference
1+
# Package Reference: `{{ groups.package[0].package }}`
2+
{{ groups.package[0].docstring }}
23

4+
{% for class_name, class_item in groups.package[0].class.items() %}
5+
## [`{{ class_name }}` class](#{{ class_name }})
6+
{{ class_item.docstring | safe }}
7+
8+
{% for method_name, method_item in class_item.method.items() %}
9+
---
10+
#### [`{{ method_name }}` method](#{{ method_item.ns_path }})
11+
[*\[source\]*]({{ groups.package[0].git_url }}{{ method_item.file }}#L{{ method_item.line_num }})
12+
13+
```python
14+
{{ method_name }}({{ method_item.arg_list_str | safe }})
15+
```
16+
{{ method_item.docstring | safe }}
17+
{{ method_item.arg_docstring | safe }}
18+
{% endfor %}
19+
{% endfor %}
20+
21+
---
22+
## [module functions](#{{ groups.package[0].package }}_functions)
23+
24+
{% for func_name, func_item in groups.package[0].function.items() %}
25+
---
26+
#### [`{{ func_name }}` method](#{{ func_item.ns_path }})
27+
[*\[source\]*]({{ groups.package[0].git_url }}{{ func_item.file }}#L{{ func_item.line_num }})
28+
29+
```python
30+
{{ func_name }}({{ func_item.arg_list_str | safe }})
31+
```
32+
{{ func_item.docstring | safe }}
33+
{{ func_item.arg_docstring | safe }}
34+
{% endfor %}
35+
36+
---
37+
## [module types](#{{ groups.package[0].package }}_types)
38+
39+
{% for type_name, type_item in groups.package[0].type.items() %}
40+
#### [`{{ type_name }}` type](#{{ type_item.ns_path }})
41+
```python
42+
{{ type_name }} = {{ type_item.obj | safe }}
43+
```
44+
{{ type_item.docstring | safe }}
45+
{% endfor %}

mkdocs.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ mkrefs_config: mkrefs.yml
77
nav:
88
- Home: index.md
99
- Other: other.md
10+
- Reference: ref.md
1011
- Glossary: glossary.md
1112
- Bibliography: biblio.md
12-
- Reference: ref.md
1313

1414
plugins:
1515
- mkrefs

mkrefs/apidocs.py

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@
2323
You're welcome.
2424
"""
2525

26-
import importlib
2726
import inspect
2827
import os
2928
import re
@@ -34,6 +33,8 @@
3433
from icecream import ic # type: ignore # pylint: disable=E0401
3534
import pathlib
3635

36+
from .util import render_reference
37+
3738

3839
class PackageDoc:
3940
"""
@@ -71,9 +72,12 @@ def __init__ (
7172
self.git_url = git_url
7273
self.class_list = class_list
7374

74-
package_obj = importlib.import_module(self.package_name)
7575
self.package_obj = sys.modules[self.package_name]
7676

77+
# prepare a file path prefix (to remove later, per file)
78+
pkg_path = os.path.dirname(inspect.getfile(self.package_obj))
79+
self.file_prefix = "/".join(pkg_path.split("/")[0:-1])
80+
7781
self.md: typing.List[str] = [
7882
"# Reference: `{}` package".format(self.package_name),
7983
]
@@ -130,7 +134,7 @@ def build (
130134
docstring = self.get_docstring(self.package_obj)
131135
self.md.extend(docstring)
132136

133-
self.meta["docstring"] = docstring
137+
self.meta["docstring"] = "\n".join(docstring).strip()
134138

135139
# find and format the class definitions
136140
for class_name in self.class_list:
@@ -303,11 +307,12 @@ class method object
303307
# link to source code in Git repo
304308
code = obj.__code__
305309
line_num = code.co_firstlineno
306-
file = code.co_filename.replace(os.getcwd(), "")
310+
file = code.co_filename.replace(self.file_prefix, "")
307311

308312
src_url = "[*\[source\]*]({}{}#L{})\n".format(self.git_url, file, line_num) # pylint: disable=W1401
309313
local_md.append(src_url)
310314

315+
func_meta["file"] = file
311316
func_meta["line_num"] = line_num
312317

313318
# format the callable signature
@@ -339,7 +344,7 @@ class method object
339344
local_md.append("")
340345

341346
func_meta["arg_dict"] = arg_dict
342-
func_meta["arg_docstring"] = arg_docstring
347+
func_meta["arg_docstring"] = "\n".join(arg_docstring).strip()
343348

344349
return line_num, local_md
345350

@@ -420,9 +425,8 @@ def extract_type_annotation (
420425
return type_name
421426

422427

423-
@classmethod
424428
def document_type (
425-
cls,
429+
self,
426430
path_list: list,
427431
name: str,
428432
obj: typing.Any,
@@ -460,7 +464,7 @@ def document_type (
460464
local_md.append("```")
461465
local_md.append("")
462466

463-
type_meta["obj"] = obj
467+
type_meta["obj"] = repr(obj)
464468

465469
return local_md
466470

@@ -610,6 +614,8 @@ def render_apidocs ( # pylint: disable=R0914
610614
returns:
611615
rendered Markdown
612616
"""
617+
groups: typing.Dict[str, list] = {}
618+
613619
package_name = local_config["apidocs"]["package"]
614620
git_url = local_config["apidocs"]["git"]
615621

@@ -632,14 +638,17 @@ def render_apidocs ( # pylint: disable=R0914
632638
pkg_doc.build()
633639

634640
# render the JSON into Markdown using the Jinja2 template
635-
with open(markdown_path, "w") as f:
636-
for line in pkg_doc.md:
637-
f.write(line)
638-
f.write("\n")
641+
groups = {
642+
"package": [ pkg_doc.meta ],
643+
}
639644

645+
render_reference(
646+
template_path,
647+
markdown_path,
648+
groups,
649+
)
640650
except Exception as e: # pylint: disable=W0703
641651
print(f"Error rendering apidocs: {e}")
642652
traceback.print_exc()
643653

644-
groups: typing.Dict[str, list] = {}
645654
return groups

mkrefs/cli.py

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,33 @@
77
import typer
88
import yaml
99

10-
from .glossary import render_glossary
10+
from .apidocs import render_apidocs
1111
from .biblio import render_biblio
12+
from .glossary import render_glossary
1213
from .util import load_kg
1314

1415

1516
APP = typer.Typer()
1617

1718

19+
@APP.command()
20+
def apidocs (
21+
config_file: str,
22+
) -> None:
23+
"""
24+
Command to generate a package reference apidocs.
25+
"""
26+
config_path = pathlib.Path(config_file)
27+
docs_dir = config_path.parent
28+
local_config = yaml.safe_load(config_path.read_text())
29+
30+
template_path = docs_dir / local_config["apidocs"]["template"]
31+
markdown_path = docs_dir / local_config["apidocs"]["page"]
32+
33+
groups = render_apidocs(local_config, template_path, markdown_path)
34+
pprint(groups)
35+
36+
1837
@APP.command()
1938
def biblio (
2039
config_file: str,

setup.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77

88

99
KEYWORDS = [
10+
"apidocs",
1011
"bibliography",
1112
"documentation",
1213
"glossary",
@@ -33,7 +34,7 @@ def parse_requirements_file (filename: str) -> typing.List:
3334
name = "mkrefs",
3435
version = mkrefs_version.__version__,
3536

36-
description = "MkDocs plugin to generate reference Markdown pages",
37+
description = "MkDocs plugin to generate semantic reference Markdown pages",
3738
long_description = pathlib.Path("README.md").read_text(),
3839
long_description_content_type = "text/markdown",
3940

0 commit comments

Comments
 (0)