Merge pull request #5 from DerwenAI/update

Update

CONTRIBUTING.md

@@ -0,0 +1,125 @@
+
+<a href="https://derwen.ai/"><img src="https://derwen.ai/static/logo_500px.png" width="122" height="122" align="right" /></a>
+
+# Welcome!
+
+Thanks for your interest in contributing to **MkRefs** 🎉 
+
+This page gives a quick overview of how things are organized and most
+importantly, how to get involved.
+
+
+## Issues and bug reports
+
+First, if you want to report a potential issue with this library, please
+[do a quick search](https://github.com/DerwenAI/mkrefs/issues)
+to see if the issue has already been reported.
+If so, it's best to simply leave a comment on an existing issue,
+rather than create a new one.
+Older issues may also include helpful info and show solutions to
+commonly encountered questions.
+
+
+## Opening new issues
+
+When opening a 
+[new issue](https://github.com/DerwenAI/mkrefs/issues/new/choose),
+please use a **descriptive title** and include information about your
+**environment** and library **installation**:
+
+  * Which operating system and version number?
+  * Which version of Python?
+  * How did you install? `pip`, `conda`, clone repo then `setup.py`, etc.
+
+Try to provide as many details as possible.
+What exactly is going wrong?
+_How_ is it failing?
+Is there an error?
+
+Please understand that in general our developer community does not
+provide support via email, Twitter DMs, and other 1:1 messaging.
+We believe that help is much more valuable when it gets **shared
+publicly**, so that more people can benefit.
+
+
+## Code of conduct
+
+In all communications and collaborations, we adhere to the
+[Contributor Covenant Code of Conduct](https://github.com/DerwenAI/mkrefs/blob/main/code_of_conduct.md).
+By participating, you are expected to follow this code.
+
+
+## Developer community
+
+If you'd like to contribute to this open source project, the best way
+to get involved with our developer community is to participate in our
+[public office hours](https://www.notion.so/KG-Community-Events-Calendar-8aacbe22efa94d9b8b39b7288e22c2d3)
+events.
+First join the 
+[*Graph-Based Data Science*](https://www.linkedin.com/groups/6725785/)
+group on LinkedIn where these meetingsget announced.
+We'll also have other developer discussions on that forum, along with
+related updates, news, conference coupons, etc.
+
+The
+[Knowledge Graph Conference](https://derwen.ai/docs/kgl/glossary/#knowledge-graph-conference)
+hosts several community resources where you can post questions and get
+help about **MkRefs** and related topics.
+Many of our developers are involved there too:
+
+  * [community Slack](https://knowledgegraphconf.slack.com/ssb/redirect) – specifically on the `#ask` channel
+
+  * [Knowledge Tech Q&A site](https://answers.knowledgegraph.tech/) for extended questions posed to experts
+
+
+## Contributing to the code base
+
+You don't have to be an expert to contribute, and we're happy to help
+you get started.
+We'll try to use the
+[`good first issue`](https://github.com/DerwenAI/mkrefs/labels/good%20first%20issue)
+tags to mark bugs and feature requests that are easy and self-contained.
+
+If you've decided to take on one of these problems, it's best to
+[fork the repo](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks)
+and do development and testing in your own fork first.
+
+Please follow the conventions for code formatting, type annotations,
+unit tests, code linting, naming conventions, and so on.
+Understand that we will not be able to accept pull requests that make
+*major overhauls* of the code base or completely change our shared
+work on formatting, testing, etc.
+
+If you need to incorporate other libraries, please discuss this with
+the other developers.
+There may be issues regarding point releases and compatibility that
+would have impact on other parts of the code base.
+
+Once you're making good progress, don't forget to add a quick comment
+to the original issue.
+You can also use the issue to ask questions, or share your work in
+progress.
+Then when you're ready to submit code for review, please use a 
+[pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)
+on our `main` repo branch.
+
+
+## Project roadmap
+
+The
+["Graph-Based Data Science"](https://derwen.ai/s/kcgh)
+talk describes the **MkRefs** open source project in much more detail,
+and discusses some about our roadmap.
+In other words, what new features and integrations are we working toward?
+
+See also our:
+
+  * [Project Board](https://github.com/DerwenAI/mkrefs/projects/1)
+  * [Milestones](https://github.com/DerwenAI/mkrefs/milestones)
+
+Suggestions and contributions for our documentation and tutorial are
+always welcomed.
+These tend to be good starting points for new contributors: you'll get
+familiar with our code samples and other resources through that.
+
+Many thanks!

README.md

@@ -22,6 +22,31 @@ added to **MkRefs** so far, although the other mentioned components
 exist in separate projects and are being integrated.
 
 
+<details>
+  <summary>Contributing Code</summary>
+
+We welcome people getting involved as contributors to this open source
+project!
+
+For detailed instructions please see:
+[CONTRIBUTING.md](https://github.com/DerwenAI/mkrefs/blob/main/CONTRIBUTING.md)
+</details>
+
+<details>
+  <summary>Semantic Versioning</summary>
+
+Before <strong>MkRefs</strong> reaches release <code>v1.0.0</code> the 
+types and classes may undergo substantial changes and the project is 
+not guaranteed to have a consistent API.
+
+Even so, we'll try to minimize breaking changes.
+We'll also be sure to provide careful notes.
+
+See:
+[changelog.txt](https://github.com/DerwenAI/mkrefs/blob/main/changelog.txt)
+</details>
+
+
 ## Why does this matter?
 
 A key takeaway is that many software engineering aspects of open
@@ -49,6 +74,53 @@ In addition, the following configuration parameter is expected:
 
   * `mkrefs_config` - YAML configuration file for **MkRefs**; e.g., `mkrefs.yml`
 
+---
+
+## API Docs
+
+A `apidocs` parameter within the configuration file expects four
+required sub-parameters:
+
+ * `page` – name of the generated Markdown page, e.g., `ref.md`
+ * `template` – a [Jinja2 template](https://jinja.palletsprojects.com/en/3.0.x/) to generate Markdown, e.g., `ref.jinja`
+ * `package` – name of the package being documented
+ * `git` – base URL for source modules in Git, e.g., `https://github.com/DerwenAI/mkrefs/blob/main`
+
+There is an optional `includes` parameter, as a list of class
+definitions to include.
+If this is used, then all other classes get ignored.
+
+See the source code in this repo for examples of how to format
+Markdown within *docstrings*.
+Specifically see the parameter documentation per method or function,
+which differs slightly from pre-exisiting frameworks.
+
+Note that the name of the generated Markdown page for the
+apidocs must appear in the `nav` section of your `mkdocs.yml`
+configuration file.
+See the structure used in this repo for an example.
+
+### Best Practices: RDF representation
+
+You can use this library outside of MkDocs, i.e., calling it
+programmatically, to generate an RDF graph to represent your package
+API reference:
+
+```
+package_name = "mkrefs"
+git_url = "https://github.com/DerwenAI/mkrefs/blob/main"
+includes = [ "MkRefsPlugin", "PackageDoc" ]
+
+pkg_doc = PackageDoc(package_name, git_url, includes)
+pkg_doc.build()
+
+kg = pkg_doc.get_rdf()
+```
+
+The `PackageDoc.get_rdf()` method returns an RDF graph as an instance
+of an `kglab.KnowledgeGraph` object.
+For more details, see <https://derwen.ai/docs/kgl/>
+
 
 ## Bibliography
 
@@ -80,7 +152,7 @@ The `queries` parameter has three required SPARQL queries:
   * `entry_author` – a mapping to identify author links for each bibliography entry
   * `entry_publisher` - the publisher link for each bibliography entry (if any)
 
-Note that the named of the generated Markdown page for the
+Note that the name 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.
@@ -149,7 +221,7 @@ The `queries` parameter has three required SPARQL queries:
   * `entry_cite` – citations to the local bibliography citekeys (if any)
   * `entry_hyp` – a mapping of [*hypernyms*](https://en.wikipedia.org/wiki/Hyponymy_and_hypernymy) (if any)
 
-Note that the named of the generated Markdown page for the glossary
+Note that the name of the generated Markdown page for the glossary
 must appear in the `nav` section of your `mkdocs.yml` configuration
 file.
 See the structure used in this repo for an example.
@@ -187,7 +259,7 @@ mkrefs glossary docs/mkrefs.yml
 
 ## What is going on here?
 
-When the plugin runs,
+For example with the bibliography use case, when the plugin runs...
 
 1. It parses its configuration file to identify the target Markdown page to generate and the Jinja2 template
 2. The plugin also loads an RDF graph from the indicated TTL file
@@ -221,7 +293,8 @@ and
 ```
 INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
   - biblio.md
-  - glossary.md 
+  - glossary.md
+  - ref.md
 ```
 
 For now, you can simply ignore both of these warnings.

changelog.txt

@@ -2,7 +2,7 @@
 
 ## 0.2.0
 
-2021-06-??
+2021-06-27
 
   * added glossary support
   * added apidocs support

code_of_conduct.md

@@ -0,0 +1,88 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our
+project and our community a harassment-free experience for everyone,
+regardless of age, body size, disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, or sexual identity and orientation.
+
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive
+environment include:
+
+  * Using welcoming and inclusive language
+  * Being respectful of differing viewpoints and experiences
+  * Gracefully accepting constructive criticism
+  * Focusing on what is best for the community
+  * Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+  * The use of sexualized language or imagery and unwelcome sexual attention or
+    advances
+  * Trolling, insulting/derogatory comments, and personal or political attacks
+  * Public or private harassment
+  * Publishing others' private information, such as a physical or electronic
+    address, without explicit permission
+  * Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of
+acceptable behavior and are expected to take appropriate and fair
+corrective action in response to any instances of unacceptable
+behavior.
+
+Project maintainers have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, or to ban
+temporarily or permanently any contributor for other behaviors that
+they deem inappropriate, threatening, offensive, or harmful.
+
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also
+applies when an individual is representing the project or its
+community in public spaces.
+Examples of representing a project or community include using an
+official project e-mail address, posting via an official social media
+account, or acting as an appointed representative at an online or
+offline event.
+Representation of a project may be further defined and clarified by
+project maintainers.
+
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported by contacting the project team at the <[email protected]>
+address.
+All complaints will be reviewed and investigated and will result in a
+response that is deemed necessary and appropriate to the
+circumstances. The project team is obligated to maintain
+confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted
+separately.
+Project maintainers who do not follow or enforce the Code of Conduct
+in good faith may face temporary or permanent repercussions as
+determined by other members of the project's leadership.
+
+
+## Attribution
+
+This Code of Conduct is adapted from version `1.4` of the 
+[Contributor Covenant](http://contributor-covenant.org/), 
+available at
+<https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+For answers to common questions about this code of conduct, see
+<https://www.contributor-covenant.org/faq>