bump to 0.0.11, improve docs

vemonet · Nov 27, 2023 · ba2bb1c · ba2bb1c
1 parent b8739d5
commit ba2bb1c
Show file tree

Hide file tree

Showing 12 changed files with 105 additions and 45 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -44,7 +44,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Generate code coverage
         run: |
-          cargo tarpaulin -p nanopub --out xml --exclude-files error.rs --verbose --timeout 120
+          cargo tarpaulin -p nanopub --out xml --exclude-files lib/src/error.rs --verbose --timeout 120
 
       - name: Upload to codecov.io
         uses: codecov/codecov-action@v2
@@ -68,12 +68,12 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - uses: actions/checkout@v4
-      - run: rustup update && cargo install mdbook-admonish
+      - run: bash ./scripts/docs-install.sh
 
-      - name: Setup mdBook
-        uses: peaceiris/actions-mdbook@v1
-        with:
-          mdbook-version: 'latest'
+      # - name: Setup mdBook
+      #   uses: peaceiris/actions-mdbook@v1
+      #   with:
+      #     mdbook-version: 'latest'
 
       - run: bash ./scripts/docs-build.sh
 

diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 .venv
 target/
+Cargo.lock
 pkg
 tarpaulin-report.html
 
@@ -12,8 +13,7 @@ js/LICENSE.txt
 
 # HTML docs generated by mdbook
 lib/docs/docs
-
-Cargo.lock
+/theme/
 
 # Build scripts
 .github/workflows/manylinux_build_script.sh

diff --git a/book.toml b/book.toml
@@ -10,12 +10,18 @@ description = "A cross-platform Rust library to sign Nanopublications, with bind
 build-dir = "./target/doc"
 create-missing = false
 
-[output.html]
-git-repository-url = "https://github.com/vemonet/nanopub-rs"
-additional-css = ["./lib/docs/assets/mdbook-admonish.css"]
-
 [preprocessor]
 
 [preprocessor.admonish]
 command = "mdbook-admonish"
 assets_version = "3.0.1" # do not edit: managed by `mdbook-admonish install`
+
+[preprocessor.pagetoc]
+
+[output.html]
+git-repository-url = "https://github.com/vemonet/nanopub-rs"
+additional-css = [
+    "lib/docs/assets/mdbook-admonish.css",
+    "theme/pagetoc.css",
+]
+additional-js  = ["theme/pagetoc.js"]
diff --git a/cli/Cargo.toml b/cli/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "nanopub-cli"
-version = "0.0.10"
+version = "0.0.11"
 description = """
 A cross-platform CLI tool written in Rust to sign Nanopublications.
 """
@@ -14,7 +14,7 @@ homepage.workspace = true
 categories.workspace = true
 
 [dependencies]
-nanopub = { version = "0.0.10", path = "../lib" }
+nanopub = { version = "0.0.11", path = "../lib" }
 clap = { version = "4.4", features = ["derive"] }
 clap_complete = "4.4"
 tokio = { version = "1.34", features = ["macros", "rt-multi-thread"] }
diff --git a/js/Cargo.toml b/js/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "nanopub-js"
-version = "0.0.10"
+version = "0.0.11"
 description = "JavaScript bindings for the Nanopub rust toolkit"
 repository = "https://github.com/vemonet/nanopub-rs/tree/main/js"
 authors.workspace = true
@@ -15,7 +15,7 @@ categories.workspace = true
 crate-type = ["cdylib"]
 
 [dependencies]
-nanopub = { version = "0.0.10", path = "../lib" }
+nanopub = { version = "0.0.11", path = "../lib" }
 wasm-bindgen = "0.2"
 wasm-bindgen-futures = "0.4"
 serde-wasm-bindgen = "0.6"

diff --git a/lib/Cargo.toml b/lib/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "nanopub"
-version = "0.0.10"
+version = "0.0.11"
 description = """
 A cross-platform Rust library to sign Nanopublications, with bindings to Python and JS (wasm)
 """

diff --git a/lib/docs/contributing.md b/lib/docs/contributing.md
@@ -137,14 +137,33 @@ cargo install cargo-release cargo-outdated
 
 > TODO: try `cargo release patch --no-tag --no-publish`
 
-## ☑️ To do
+## ️🗺️ Architecture details
 
-- [ ] Integrate to the python `nanopub` library to perform signing?
-- [ ] Add Ruby bindings? https://docs.rs/magnus/latest/magnus https://github.com/ankane/tokenizers-ruby
-- [ ] Add Java bindings? https://docs.rs/jni/latest/jni
-- [ ] Add brew packaging (c.f. [ripgrep](https://github.com/BurntSushi/ripgrep/blob/master/pkg/brew/ripgrep-bin.rb))?
+### 🗃️ Folder structure
+
+```
+nanopub-rs/
+├── lib/
+│   ├── src/
+│   │   └── 🦀 Source code for the core Rust crate.
+│   ├── tests/
+│   │   └── 🧪 Tests for the core Rust crate.
+│   └── docs/
+│       └── 📖 Markdown and HTML files for the documentation website.
+├── python/
+│   └── 🐍 Python bindings for interacting with the Rust crate.
+├── js/
+│   └── 🌐 JavaScript bindings for integrating into JS environments.
+├── cli/
+│   └── ⌨️ Scripts for the command-line interface.
+├── scripts/
+│   └── 🛠️ Development scripts (build docs, testing).
+└── .github/
+    └── workflows/
+        └── ⚙️ Automated CI/CD workflows.
+```
 
-## ✒️ Nanopub signing process
+### ✒️ Nanopub signing process
 
 - Preliminary nanopub is created with blank space in URIs at the places where the trusty URI code will appear (normalized URI: `https://w3id.org/np/ `, cf. [code](https://github.com/Nanopublication/nanopub-java/blob/22bba0e79508309f1c6163970f49ab596beadeb0/src/main/java/org/nanopub/trusty/TempUriReplacer.java#L12)); this includes the signature part, except the triple that is stating the actual signature
 - Preliminary nanopub is serialized in a normalized fashion (basically each quad on four lines with minimal escaping)
@@ -153,6 +172,13 @@ cargo install cargo-release cargo-outdated
 - Trusty URI code is calculated on normalized representation that includes signature
 - Trusty URI code is added in place of all the occurrences of blank spaces in the URIs, leading to the final trusty nanopub
 
+### ☑️ To do
+
+- [ ] Integrate to the python `nanopub` library to perform signing?
+- [ ] Add Ruby bindings? https://docs.rs/magnus/latest/magnus https://github.com/ankane/tokenizers-ruby
+- [ ] Add Java bindings? https://docs.rs/jni/latest/jni
+- [ ] Add brew packaging (c.f. [ripgrep](https://github.com/BurntSushi/ripgrep/blob/master/pkg/brew/ripgrep-bin.rb))?
+
 ## ⏱️ Speed comparison
 
 Speed taken when signing a nanopub using different languages implementations (in this order: [java](https://github.com/Nanopublication/nanopub-java), [python](https://github.com/fair-workflows/nanopub), rust):

diff --git a/lib/docs/introduction.md b/lib/docs/introduction.md
@@ -4,38 +4,53 @@
 [![PyPI](https://img.shields.io/pypi/v/nanopub-sign)](https://pypi.org/project/nanopub-sign/)
 [![npm](https://img.shields.io/npm/v/@nanopub/sign)](https://www.npmjs.com/package/@nanopub/sign)
 
-This project aims to provide a comprehensive cross-platform toolkit to sign, publish, and check **[Nanopublications](https://nanopub.net)**.
+This project aims to provide a comprehensive cross-platform toolkit to sign, publish, and verify **[Nanopublications](https://nanopub.net)**.
 
-It enables developers to:
+Whether you're a developer looking to integrate nanopub functionalities into your application or a researcher seeking an efficient way to handle nanopublications, `nanopub-rs` offers a suite of tools tailored to meet  your needs.
 
-- Sign and publish nanopubs using a RSA private key, with support for configuration through a `profile.yml` file.
-- Check the validity of signed or unsigned nanopubs.
+## 🔑 Key Features
 
-It is packaged to be used easily through various popular interfaces:
+### ✨ Nanopub management
 
-- ⌨️ Binary with a CLI for use in the terminal
-- 🦀 Crate `nanopub` for Rust
-- 🐍 Pip package `nanopub-sign` for Python
-- 📦️ NPM package `@nanopub/sign` for JavaScript (compiled to WebAssembly) in the browser, or with NodeJS
+- ✍️ **Sign & Publish** nanopubs using a RSA private key. Customize your workflow with a `profile.yml` file.
+- 🔍 **Verify**: ensure the integrity of nanopubs by checking their validity, whether they are signed or unsigned.
+- 📥 **Fetch** nanopubs from the network using their URI.
 
-On all platforms:
+### 📦️ Packaged for multiple interfaces
+
+This library is packaged for easy use across various interfaces and languages:
+
+- ⌨️  **Terminal enthusiasts**: binary with a Command Line Interface (CLI) for straightforward terminal operations.
+- 🦀 **Rust developers**: available as a Rust crate `nanopub`.
+- 🐍 **Python programmers**: available as a Python pip package `nanopub-sign`.
+- 🌐 **Web developers**: available as a NPM package `@nanopub/sign`, compiled to [WebAssembly](https://webassembly.org/), for browser integrations with JavaScript, or NodeJS.
+
+### ⚔️ Cross-platform support
+
+It runs seamlessly on:
 
 - 🐧 Linux
 - 🍎 MacOS
 - 🪟 Windows
 - 🦊 Web browsers
 
-The library automatically handles most RDF serializations supporting quads for the nanopub:
+### 🧩 RDF serialization support
+
+The library handles most RDF serializations supporting quads, including TriG, Nquads, and JSON-LD.
+
+### 📝 Automated metadata creation
+
+When you sign a nanopub, if it has not already been defined in the pubinfo graph yet:
+
+- 🕓 **Automatic timestamp**: the `dct:created` attribute is used to add the date and time of creation.
+- 🪪 **Creator identification**: if an ORCID is provided in the profile, it's added using `dct:creator`. The library also checks for ORCID set with `prov:wasAttributedTo` or `pav:createdBy`.
 
-- TriG
-- Nquads
-- JSON-LD
+## 👆 Interactive demo
 
-When signing a nanopub, some metadata are created automatically in the pubinfo graph if they are not already set in the provided RDF:
+Experience `nanopub-rs` in action! Visit the **[demo page](https://vemonet.github.io/nanopub-rs/demo.html)** to sign Nanopublications, or generate and register a new key pair, directly in your browser using the NPM version of this library.
 
-- Date and time of the nanopub creation is added using `dct:created`
-- ORCID of the creator is added using `dct:creator` if an ORCID was provided in the profile used to sign the nanopub (we also check if the ORCID has been set with `prov:wasAttributedTo` or `pav:createdBy`)
+## 🚀 Getting started
 
-Checkout the page most adapted to your use-case to get started.
+Checkout the page most adapted to your use-case to get started!
 
-> 💡 If you are facing any problem, or have ideas to help improve this project, please [create an issue](https://github.com/vemonet/nanopub-rs/issues) on GitHub.
+> 💡 **Need Help or Have Suggestions?** We welcome your input and feedback! If you encounter any issues or have ideas to enhance this tool, please [create an issue](https://github.com/vemonet/nanopub-rs/issues) on our GitHub repository.
diff --git a/lib/docs/use_javascript.md b/lib/docs/use_javascript.md
@@ -4,6 +4,10 @@
 
 You can easily publish Nanopubs from JavaScript, or TypeScript.
 
+```admonish example title="Demo"
+Visit the **[demo page](https://vemonet.github.io/nanopub-rs/demo.html)** to sign nanopubs, or generate and register a new key pair, directly in your browser using this NPM package. You can checkout the [`demo.html`](https://github.com/vemonet/nanopub-rs/blob/main/lib/docs/demo.html) file as an example to use the package directly from HTML/JS.
+```
+
 ## 📥️ Install
 
 Install the `npm` package (use `yarn` or `pnpm` if you prefer):

diff --git a/python/Cargo.toml b/python/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "nanopub-sign"
-version = "0.0.10"
+version = "0.0.11"
 description = "Python bindings for the Nanopub rust toolkit"
 repository = "https://github.com/vemonet/nanopub-rs/tree/main/python"
 authors.workspace = true
@@ -16,7 +16,7 @@ name = "nanopub_sign"
 crate-type = ["cdylib"]
 
 [dependencies]
-nanopub = { version = "0.0.10", path = "../lib" }
+nanopub = { version = "0.0.11", path = "../lib" }
 pyo3 = { version = "0.20", features = ["extension-module"] }
 pyo3-asyncio = "0.20"
 tokio = { version = "1.34", features = ["rt-multi-thread"] }
diff --git a/scripts/docs-install.sh b/scripts/docs-install.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -e
+# Script to install dependencies for development and enable pre-commit hooks
+
+rustup update
+
+cargo install mdbook mdbook-admonish mdbook-pagetoc
diff --git a/scripts/install-dev.sh b/scripts/install-dev.sh
@@ -10,6 +10,8 @@ pip install maturin pre-commit
 rustup update
 rustup component add rustfmt clippy
 
-cargo install wasm-pack cargo-tarpaulin mdbook mdbook-admonish
+cargo install wasm-pack cargo-tarpaulin
+
+source scripts/docs-install.sh
 
 pre-commit install