Update sources and docs (#1)

1. Adds two new sources for GO and Monarch JSON LD contexts
2. Adds documentation for each source

Cargo.toml

@@ -12,7 +12,7 @@ edition = "2021"
 description = "Idiomatic conversion between URIs and compact URIs (CURIEs)"
 readme = "README.md"
 license-file = "LICENSE"
-keywords = ["semantic web", "linked data", "linked open data"]
+keywords = ["semantic-web", "linked-data", "linked-open-data"]
 categories = ["science", "encoding"]
 repository = "https://github.com/biopragmatics/curies.rs"
 homepage = "https://biopragmatics.github/curies.rs"

README.md

@@ -34,16 +34,25 @@ cargo install wasm-pack cargo-tarpaulin mdbook mdbook-admonish
 
 > If you are using VSCode we strongly recommend to install the `rust-lang.rust-analyzer` extension.
 
-## 🧪 Run tests
+
+## Development
+
+### 🧪 Run tests
 
 Run tests and display prints:
 
-```bash
+```shell
 cargo test -- --nocapture
 ```
 
-## 🧹 Format
+### 🧹 Format
 
-```bash
+```shell
 cargo fmt
 ```
+
+### 📖 Documentation
+
+```shell
+cargo doc --open
+```

lib/src/lib.rs

@@ -304,7 +304,9 @@ impl DataSource for &Path {
 
 // Python API: https://github.com/cthoyt/curies/blob/main/src/curies/api.py#L1099
 // HashSet more efficient than Vec: https://stackoverflow.com/questions/3185226/huge-performance-difference-between-vector-and-hashset
-// But HashSet are not ordered, while Vec are ordered
+// But HashSet are not ordered, while Vec are ordered.
+// This choice was made since Pydantic is more convenient to use with lists since they
+// are directly JSON-serializable.
 
 // /// Stores the prefix and local unique identifier
 // /// for a compact URI (CURIE)

lib/src/sources.rs

@@ -1,6 +1,111 @@
+//! Contains functions for getting pre-defined contexts
+
 use crate::{error::CuriesError, Converter};
 
-/// Get the latest OBO Foundry context.
+/// Get the latest [OBO Foundry context](http://purl.obolibrary.org/meta/obo_context.jsonld).
+///
+/// The OBO Foundry context is a simple prefix map stored in a JSON-LD file.
+/// It contains OBO Foundry preferred prefixes and OBO PURL expansions,
+/// but no synonyms.
+///
+/// # Examples
+///
+/// ```rust
+/// use curies::sources::{get_obo_converter};
+/// use tokio::{runtime};
+///
+/// let rt = runtime::Runtime::new().expect("Failed to create Tokio runtime");
+/// let converter = rt.block_on(async {
+///      get_obo_converter().await
+/// }).expect("Failed to create the OBO converter");
+///
+/// let uri = converter.expand("DOID:1234").unwrap();
+/// assert_eq!(uri, "http://purl.obolibrary.org/obo/DOID_1234");
+///
+/// let unregistered_uri = converter.expand("missing.prefix:0000001");
+/// assert!(unregistered_uri.is_err());
+///
+/// let curie = converter.compress("http://purl.obolibrary.org/obo/DOID_1234").unwrap();
+/// assert_eq!(curie, "DOID:1234");
+///
+/// let unregistered_curie = converter.compress("http://example.org/missing.prefix:0000001");
+/// assert!(unregistered_curie.is_err());
+/// ```
 pub async fn get_obo_converter() -> Result<Converter, CuriesError> {
     Converter::from_jsonld("http://purl.obolibrary.org/meta/obo_context.jsonld").await
 }
+
+/// Get the Prefix Commons-maintained [Monarch Initiative
+/// context](https://github.com/prefixcommons/prefixcommons-py/blob/master/prefixcommons/registry/monarch_context.jsonld)
+///
+/// The Monarch Initiative context is a simple prefix map stored in a JSON-LD file.
+/// It contains a project-specific mix of prefixes from GO, OBO, and Identifiers.org.
+///
+/// Note, this is not a carefully constructed context, as there are overlapping entries
+/// such as:
+///
+/// - TrEMBL and `http://purl.uniprot.org/uniprot/`
+/// - SwissProt and `http://identifiers.org/SwissProt:`
+/// - UniProtKB" and `http://identifiers.org/uniprot/`
+///
+/// # Examples
+///
+/// ```rust
+/// use curies::sources::{get_monarch_converter};
+/// use tokio::{runtime};
+///
+/// let rt = runtime::Runtime::new().expect("Failed to create Tokio runtime");
+/// let converter = rt.block_on(async {
+///      get_monarch_converter().await
+/// }).expect("Failed to create the GO converter");
+///
+/// let uri = converter.expand("CHEBI:24867").unwrap();
+/// assert_eq!(uri, "http://purl.obolibrary.org/obo/CHEBI_24867");
+///
+/// let unregistered_uri = converter.expand("addgene:50943");
+/// assert!(unregistered_uri.is_err(), "AddGene is not registered in the Monarch context");
+///
+/// let curie = converter.compress("http://purl.obolibrary.org/obo/CHEBI_24867").unwrap();
+/// assert_eq!(curie, "CHEBI:24867");
+///
+/// let unregistered_curie = converter.compress("http://addgene.org/50943");
+/// assert!(unregistered_curie.is_err(), "AddGene is not registered in the Monarch context");
+/// ```
+pub async fn get_monarch_converter() -> Result<Converter, CuriesError> {
+    Converter::from_jsonld("https://raw.githubusercontent.com/prefixcommons/prefixcommons-py/master/prefixcommons/registry/monarch_context.jsonld").await
+}
+
+/// Get the Prefix Commons-maintained [Gene Ontology (GO)
+/// context](https://github.com/prefixcommons/prefixcommons-py/blob/master/prefixcommons/registry/go_context.jsonld)
+///
+/// The Gene Ontology context is a simple prefix map stored in a JSON-LD file.
+/// It contains prefixes corresponding to semantic spaces that are useful for
+/// modeling the molecular functions, cellular components, and biological processes
+/// that genes take part in.
+///
+/// # Examples
+///
+/// ```rust
+/// use curies::sources::{get_go_converter};
+/// use tokio::{runtime};
+///
+/// let rt = runtime::Runtime::new().expect("Failed to create Tokio runtime");
+/// let converter = rt.block_on(async {
+///      get_go_converter().await
+/// }).expect("Failed to create the GO converter");
+///
+/// let uri = converter.expand("NCBIGene:100010").unwrap();
+/// assert_eq!(uri, "http://identifiers.org/ncbigene/100010");
+///
+/// let unregistered_uri = converter.expand("DOID:1234");
+/// assert!(unregistered_uri.is_err(), "DOID is not registered in the GO context");
+///
+/// let curie = converter.compress("http://identifiers.org/ncbigene/100010").unwrap();
+/// assert_eq!(curie, "NCBIGene:100010");
+///
+/// let unregistered_curie = converter.compress("http://purl.obolibrary.org/obo/DOID_1234");
+/// assert!(unregistered_curie.is_err(), "DOID is not registered in the GO context");
+/// ```
+pub async fn get_go_converter() -> Result<Converter, CuriesError> {
+    Converter::from_jsonld("https://raw.githubusercontent.com/prefixcommons/prefixcommons-py/master/prefixcommons/registry/go_context.jsonld").await
+}