Skip to content

Commit d78d614

Browse files
cetericeteri
committed
first release of APIdocs support
1 parent 2d85ab8 commit d78d614

File tree

4 files changed

+291
-5
lines changed

4 files changed

+291
-5
lines changed

‎CONTRIBUTING.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
2+
<a href="https://derwen.ai/"><img src="https://derwen.ai/static/logo_500px.png" width="122" height="122" align="right" /></a>
3+
4+
# Welcome!
5+
6+
Thanks for your interest in contributing to **MkRefs** 🎉
7+
8+
This page gives a quick overview of how things are organized and most
9+
importantly, how to get involved.
10+
11+
12+
## Issues and bug reports
13+
14+
First, if you want to report a potential issue with this library, please
15+
[do a quick search](https://github.com/DerwenAI/mkrefs/issues)
16+
to see if the issue has already been reported.
17+
If so, it's best to simply leave a comment on an existing issue,
18+
rather than create a new one.
19+
Older issues may also include helpful info and show solutions to
20+
commonly encountered questions.
21+
22+
23+
## Opening new issues
24+
25+
When opening a
26+
[new issue](https://github.com/DerwenAI/mkrefs/issues/new/choose),
27+
please use a **descriptive title** and include information about your
28+
**environment** and library **installation**:
29+
30+
* Which operating system and version number?
31+
* Which version of Python?
32+
* How did you install? `pip`, `conda`, clone repo then `setup.py`, etc.
33+
34+
Try to provide as many details as possible.
35+
What exactly is going wrong?
36+
_How_ is it failing?
37+
Is there an error?
38+
39+
Please understand that in general our developer community does not
40+
provide support via email, Twitter DMs, and other 1:1 messaging.
41+
We believe that help is much more valuable when it gets **shared
42+
publicly**, so that more people can benefit.
43+
44+
45+
## Code of conduct
46+
47+
In all communications and collaborations, we adhere to the
48+
[Contributor Covenant Code of Conduct](https://github.com/DerwenAI/mkrefs/blob/main/code_of_conduct.md).
49+
By participating, you are expected to follow this code.
50+
51+
52+
## Developer community
53+
54+
If you'd like to contribute to this open source project, the best way
55+
to get involved with our developer community is to participate in our
56+
[public office hours](https://www.notion.so/KG-Community-Events-Calendar-8aacbe22efa94d9b8b39b7288e22c2d3)
57+
events.
58+
First join the
59+
[*Graph-Based Data Science*](https://www.linkedin.com/groups/6725785/)
60+
group on LinkedIn where these meetingsget announced.
61+
We'll also have other developer discussions on that forum, along with
62+
related updates, news, conference coupons, etc.
63+
64+
The
65+
[Knowledge Graph Conference](https://derwen.ai/docs/kgl/glossary/#knowledge-graph-conference)
66+
hosts several community resources where you can post questions and get
67+
help about **MkRefs** and related topics.
68+
Many of our developers are involved there too:
69+
70+
* [community Slack](https://knowledgegraphconf.slack.com/ssb/redirect) – specifically on the `#ask` channel
71+
72+
* [Knowledge Tech Q&A site](https://answers.knowledgegraph.tech/) for extended questions posed to experts
73+
74+
75+
## Contributing to the code base
76+
77+
You don't have to be an expert to contribute, and we're happy to help
78+
you get started.
79+
We'll try to use the
80+
[`good first issue`](https://github.com/DerwenAI/mkrefs/labels/good%20first%20issue)
81+
tags to mark bugs and feature requests that are easy and self-contained.
82+
83+
If you've decided to take on one of these problems, it's best to
84+
[fork the repo](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks)
85+
and do development and testing in your own fork first.
86+
87+
Please follow the conventions for code formatting, type annotations,
88+
unit tests, code linting, naming conventions, and so on.
89+
Understand that we will not be able to accept pull requests that make
90+
*major overhauls* of the code base or completely change our shared
91+
work on formatting, testing, etc.
92+
93+
If you need to incorporate other libraries, please discuss this with
94+
the other developers.
95+
There may be issues regarding point releases and compatibility that
96+
would have impact on other parts of the code base.
97+
98+
Once you're making good progress, don't forget to add a quick comment
99+
to the original issue.
100+
You can also use the issue to ask questions, or share your work in
101+
progress.
102+
Then when you're ready to submit code for review, please use a
103+
[pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)
104+
on our `main` repo branch.
105+
106+
107+
## Project roadmap
108+
109+
The
110+
["Graph-Based Data Science"](https://derwen.ai/s/kcgh)
111+
talk describes the **MkRefs** open source project in much more detail,
112+
and discusses some about our roadmap.
113+
In other words, what new features and integrations are we working toward?
114+
115+
See also our:
116+
117+
* [Project Board](https://github.com/DerwenAI/mkrefs/projects/1)
118+
* [Milestones](https://github.com/DerwenAI/mkrefs/milestones)
119+
120+
Suggestions and contributions for our documentation and tutorial are
121+
always welcomed.
122+
These tend to be good starting points for new contributors: you'll get
123+
familiar with our code samples and other resources through that.
124+
125+
Many thanks!

‎README.md

+77-4
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,31 @@ added to **MkRefs** so far, although the other mentioned components
2222
exist in separate projects and are being integrated.
2323

2424

25+
<details>
26+
<summary>Contributing Code</summary>
27+
28+
We welcome people getting involved as contributors to this open source
29+
project!
30+
31+
For detailed instructions please see:
32+
[CONTRIBUTING.md](https://github.com/DerwenAI/mkrefs/blob/main/CONTRIBUTING.md)
33+
</details>
34+
35+
<details>
36+
<summary>Semantic Versioning</summary>
37+
38+
Before <strong>MkRefs</strong> reaches release <code>v1.0.0</code> the
39+
types and classes may undergo substantial changes and the project is
40+
not guaranteed to have a consistent API.
41+
42+
Even so, we'll try to minimize breaking changes.
43+
We'll also be sure to provide careful notes.
44+
45+
See:
46+
[changelog.txt](https://github.com/DerwenAI/mkrefs/blob/main/changelog.txt)
47+
</details>
48+
49+
2550
## Why does this matter?
2651

2752
A key takeaway is that many software engineering aspects of open
@@ -49,6 +74,53 @@ In addition, the following configuration parameter is expected:
4974
5075
* `mkrefs_config` - YAML configuration file for **MkRefs**; e.g., `mkrefs.yml`
5176

77+
---
78+
79+
## API Docs
80+
81+
A `apidocs` parameter within the configuration file expects four
82+
required sub-parameters:
83+
84+
* `page` – name of the generated Markdown page, e.g., `ref.md`
85+
* `template` – a [Jinja2 template](https://jinja.palletsprojects.com/en/3.0.x/) to generate Markdown, e.g., `ref.jinja`
86+
* `package` – name of the package being documented
87+
* `git` – base URL for source modules in Git, e.g., `https://github.com/DerwenAI/mkrefs/blob/main`
88+
89+
There is an optional `includes` parameter, as a list of class
90+
definitions to include.
91+
If this is used, then all other classes get ignored.
92+
93+
See the source code in this repo for examples of how to format
94+
Markdown within *docstrings*.
95+
Specifically see the parameter documentation per method or function,
96+
which differs slightly from pre-exisiting frameworks.
97+
98+
Note that the name of the generated Markdown page for the
99+
apidocs must appear in the `nav` section of your `mkdocs.yml`
100+
configuration file.
101+
See the structure used in this repo for an example.
102+
103+
### Best Practices: RDF representation
104+
105+
You can use this library outside of MkDocs, i.e., calling it
106+
programmatically, to generate an RDF graph to represent your package
107+
API reference:
108+
109+
```
110+
package_name = "mkrefs"
111+
git_url = "https://github.com/DerwenAI/mkrefs/blob/main"
112+
includes = [ "MkRefsPlugin", "PackageDoc" ]
113+
114+
pkg_doc = PackageDoc(package_name, git_url, includes)
115+
pkg_doc.build()
116+
117+
kg = pkg_doc.get_rdf()
118+
```
119+
120+
The `PackageDoc.get_rdf()` method returns an RDF graph as an instance
121+
of an `kglab.KnowledgeGraph` object.
122+
For more details, see <https://derwen.ai/docs/kgl/>
123+
52124

53125
## Bibliography
54126

@@ -80,7 +152,7 @@ The `queries` parameter has three required SPARQL queries:
80152
* `entry_author` – a mapping to identify author links for each bibliography entry
81153
* `entry_publisher` - the publisher link for each bibliography entry (if any)
82154

83-
Note that the named of the generated Markdown page for the
155+
Note that the name of the generated Markdown page for the
84156
bibliography must appear in the `nav` section of your `mkdocs.yml`
85157
configuration file.
86158
See the structure used in this repo for an example.
@@ -149,7 +221,7 @@ The `queries` parameter has three required SPARQL queries:
149221
* `entry_cite` – citations to the local bibliography citekeys (if any)
150222
* `entry_hyp` – a mapping of [*hypernyms*](https://en.wikipedia.org/wiki/Hyponymy_and_hypernymy) (if any)
151223

152-
Note that the named of the generated Markdown page for the glossary
224+
Note that the name of the generated Markdown page for the glossary
153225
must appear in the `nav` section of your `mkdocs.yml` configuration
154226
file.
155227
See the structure used in this repo for an example.
@@ -187,7 +259,7 @@ mkrefs glossary docs/mkrefs.yml
187259

188260
## What is going on here?
189261

190-
When the plugin runs,
262+
For example with the bibliography use case, when the plugin runs...
191263

192264
1. It parses its configuration file to identify the target Markdown page to generate and the Jinja2 template
193265
2. The plugin also loads an RDF graph from the indicated TTL file
@@ -221,7 +293,8 @@ and
221293
```
222294
INFO - The following pages exist in the docs directory, but are not included in the "nav" configuration:
223295
- biblio.md
224-
- glossary.md
296+
- glossary.md
297+
- ref.md
225298
```
226299
227300
For now, you can simply ignore both of these warnings.

‎changelog.txt

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

33
## 0.2.0
44

5-
2021-06-??
5+
2021-06-27
66

77
* added glossary support
88
* added apidocs support

‎code_of_conduct.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as
6+
contributors and maintainers pledge to make participation in our
7+
project and our community a harassment-free experience for everyone,
8+
regardless of age, body size, disability, ethnicity, sex
9+
characteristics, gender identity and expression, level of experience,
10+
education, socio-economic status, nationality, personal appearance,
11+
race, or sexual identity and orientation.
12+
13+
14+
## Our Standards
15+
16+
Examples of behavior that contributes to creating a positive
17+
environment include:
18+
19+
* Using welcoming and inclusive language
20+
* Being respectful of differing viewpoints and experiences
21+
* Gracefully accepting constructive criticism
22+
* Focusing on what is best for the community
23+
* Showing empathy towards other community members
24+
25+
Examples of unacceptable behavior by participants include:
26+
27+
* The use of sexualized language or imagery and unwelcome sexual attention or
28+
advances
29+
* Trolling, insulting/derogatory comments, and personal or political attacks
30+
* Public or private harassment
31+
* Publishing others' private information, such as a physical or electronic
32+
address, without explicit permission
33+
* Other conduct which could reasonably be considered inappropriate in a
34+
professional setting
35+
36+
37+
## Our Responsibilities
38+
39+
Project maintainers are responsible for clarifying the standards of
40+
acceptable behavior and are expected to take appropriate and fair
41+
corrective action in response to any instances of unacceptable
42+
behavior.
43+
44+
Project maintainers have the right and responsibility to remove, edit,
45+
or reject comments, commits, code, wiki edits, issues, and other
46+
contributions that are not aligned to this Code of Conduct, or to ban
47+
temporarily or permanently any contributor for other behaviors that
48+
they deem inappropriate, threatening, offensive, or harmful.
49+
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all project spaces, and it also
54+
applies when an individual is representing the project or its
55+
community in public spaces.
56+
Examples of representing a project or community include using an
57+
official project e-mail address, posting via an official social media
58+
account, or acting as an appointed representative at an online or
59+
offline event.
60+
Representation of a project may be further defined and clarified by
61+
project maintainers.
62+
63+
64+
## Enforcement
65+
66+
Instances of abusive, harassing, or otherwise unacceptable behavior
67+
may be reported by contacting the project team at the <[email protected]>
68+
address.
69+
All complaints will be reviewed and investigated and will result in a
70+
response that is deemed necessary and appropriate to the
71+
circumstances. The project team is obligated to maintain
72+
confidentiality with regard to the reporter of an incident.
73+
Further details of specific enforcement policies may be posted
74+
separately.
75+
Project maintainers who do not follow or enforce the Code of Conduct
76+
in good faith may face temporary or permanent repercussions as
77+
determined by other members of the project's leadership.
78+
79+
80+
## Attribution
81+
82+
This Code of Conduct is adapted from version `1.4` of the
83+
[Contributor Covenant](http://contributor-covenant.org/),
84+
available at
85+
<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
86+
87+
For answers to common questions about this code of conduct, see
88+
<https://www.contributor-covenant.org/faq>

0 commit comments

Comments
 (0)