Add mdbook docs in lib/docs, scripts for development in a scripts/ fo…

…lder
biopragmatics · Dec 15, 2023 · a8f0375 · a8f0375
1 parent ff60688
commit a8f0375
Show file tree

Hide file tree

Showing 18 changed files with 593 additions and 29 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -50,34 +50,34 @@ jobs:
           fail_ci_if_error: false
       #     token: ${{secrets.CODECOV_TOKEN}}
 
-  # docs:
-  #   name: 📖 Update docs
-  #   runs-on: ubuntu-latest
-  #   permissions:
-  #     contents: read
-  #     pages: write
-  #     id-token: write
-  #   # Allow one concurrent deployment
-  #   concurrency:
-  #     group: "pages"
-  #     cancel-in-progress: true
-  #   environment:
-  #     name: github-pages
-  #     url: ${{ steps.deployment.outputs.page_url }}
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #     - run: bash ./scripts/docs-install.sh
+  docs:
+    name: 📖 Update docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    # Allow one concurrent deployment
+    concurrency:
+      group: "pages"
+      cancel-in-progress: true
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash ./scripts/docs-install.sh
 
-  #     - run: bash ./scripts/docs-build.sh
+      - run: bash ./scripts/docs-build.sh
 
-  #     - name: Setup Pages
-  #       uses: actions/configure-pages@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
 
-  #     - name: Upload artifact
-  #       uses: actions/upload-pages-artifact@v1
-  #       with:
-  #         path: './target/doc'
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './target/doc'
 
-  #     - name: Deploy to GitHub Pages
-  #       id: deployment
-  #       uses: actions/deploy-pages@v2
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
diff --git a/book.toml b/book.toml
@@ -0,0 +1,30 @@
+[book]
+authors = [
+    "Charles Tapley Hoyt <cthoyt@gmail.com>",
+    "Vincent Emonet <vincent.emonet@gmail.com>",
+]
+language = "en"
+multilingual = false
+src = "./lib/docs"
+title = "CURIEs"
+description = "A cross-platform library for idiomatic conversion between URIs and compact URIs (CURIEs)"
+
+[build]
+build-dir = "./target/doc"
+create-missing = false
+
+[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/biopragmatics/curies.rs"
+additional-css = [
+    "theme/mdbook-admonish.css",
+    "theme/pagetoc.css",
+]
+additional-js  = ["theme/pagetoc.js"]
diff --git a/js/index.html b/js/index.html
@@ -2,11 +2,10 @@
 <html lang="en-US">
   <head>
     <meta charset="utf-8" />
-    <title>CURIEs dev</title>
+    <title>CURIEs example</title>
   </head>
 
   <body>
-    <p>DOID:</p>
     <p id="compressed"></p>
     <p id="expanded"></p>
 
@@ -19,6 +18,7 @@
         console.log(rec1.toString());
         console.log(rec1.toJs());
 
+        // Populate the Converter with records, or import existing converters:
         // const converter = new Converter();
         // converter.addRecord(rec1);
 

diff --git a/lib/docs/SUMMARY.md b/lib/docs/SUMMARY.md
@@ -0,0 +1,7 @@
+# Summary
+
+- [Introduction](introduction.md)
+- [Use Rust crate](use_rust.md)
+- [Use Python package](use_python.md)
+- [Use NPM package](use_javascript.md)
+- [Contributing](contributing.md)
diff --git a/lib/docs/contributing.md b/lib/docs/contributing.md
@@ -0,0 +1,179 @@
+# 🛠️ Contributing
+
+The usual process to make a contribution is to:
+
+1. Check for existing related [issues on GitHub](https://github.com/biopragmatics/curies.rs/issues)
+2. [Fork](https://github.com/biopragmatics/curies.rs/fork) the repository and create a new branch
+3. Make your changes
+4. Make sure formatting, linting and tests passes.
+5. Add tests if possible to cover the lines you added.
+6. Commit, and send a Pull Request.
+
+## ️🗺️ Architecture details
+
+### 🗃️ Folder structure
+
+```
+curies.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.
+├── scripts/
+│   └── 🛠️ Development scripts (build docs, testing).
+└── .github/
+    └── workflows/
+        └── ⚙️ Automated CI/CD workflows.
+```
+
+## 🧑‍💻 Development workflow
+
+[![Build](https://github.com/biopragmatics/curies.rs/actions/workflows/build.yml/badge.svg)](https://github.com/biopragmatics/curies.rs/actions/workflows/build.yml) [![Lint and Test](https://github.com/biopragmatics/curies.rs/actions/workflows/test.yml/badge.svg)](https://github.com/biopragmatics/curies.rs/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/biopragmatics/curies.rs/graph/badge.svg?token=BF15PSO6GN)](https://codecov.io/gh/biopragmatics/curies.rs) [![dependency status](https://deps.rs/repo/github/biopragmatics/curies.rs/status.svg)](https://deps.rs/repo/github/biopragmatics/curies.rs)
+
+[Rust](https://www.rust-lang.org/tools/install), python, and NodeJS are required for development.
+
+Install development dependencies:
+
+```bash
+# Activate python virtual env
+python3 -m venv .venv
+source .venv/bin/activate
+# Install python dependencies
+pip install maturin
+# Install rust dev tools
+rustup update
+rustup component add rustfmt clippy
+cargo install wasm-pack cargo-tarpaulin mdbook mdbook-admonish cargo-make
+```
+
+### 📥️ Clone the repository
+
+Clone the `curies.rs` repository, `cd` into it, and create a new branch for your contribution:
+
+```bash
+cd curies.rs
+git checkout -b add-my-contribution
+```
+
+###  🧪 Run tests
+
+Run tests for all packages:
+
+```bash
+cargo test
+```
+
+Display prints:
+
+```bash
+cargo test -- --nocapture
+```
+
+Run a specific test:
+
+```bash
+cargo test new_empty_converter -- --nocapture
+```
+
+If tests panic without telling on which test it failed:
+
+```bash
+cargo test -- --test-threads=1
+```
+
+Test the `curies` crate with code coverage:
+
+```bash
+cargo tarpaulin -p curies --out html
+```
+
+### 🐍 Run python
+
+Build the pip package, and run the `python/try.py` script:
+
+```bash
+./scripts/build-python.sh
+```
+
+Or just run the script:
+
+```bash
+source .venv/bin/activate
+python python/try.py
+```
+
+### 🟨 Run JavaScript
+
+Build the npm package:
+
+```bash
+./scripts/build-js.py
+```
+
+Start a web server:
+
+```bash
+python -m http.server 3000 --directory ./js
+```
+
+Open [localhost:3000](http://localhost:3000) in your web browser.
+
+### ✨ Format
+
+```bash
+cargo fmt
+```
+
+### 🧹 Lint
+
+```bash
+cargo clippy --all --all-targets --all-features
+```
+
+### 📖 Generate docs locally
+
+Install dependencies:
+
+```bash
+./scripts/docs-install.sh
+```
+
+Build and serve:
+
+```bash
+./scripts/docs-serve.sh
+```
+
+### 🏷️ New release
+
+Publishing artifacts will be done by the `build.yml` workflow, make sure you have set the following tokens as secrets for this repository: `PYPI_TOKEN`, `NPM_TOKEN`, `CRATES_IO_TOKEN`, `CODECOV_TOKEN`
+
+Install dependency:
+
+```bash
+cargo install cargo-outdated
+```
+
+1. Make sure dependencies have been updated:
+
+   ```bash
+   cargo update
+   cargo outdated
+   ```
+
+2. Bump the version in the `Cargo.toml` file in folders `lib/`, `python`, `js`
+
+   ```bash
+   ./scripts/bump.sh 0.0.2
+   ```
+
+3. Commit, push, and create a new release on GitHub
+
+4. The `build.yml` workflow will automatically build artifacts (binary, pip wheel, npm package), and add them to the new release.
diff --git a/lib/docs/introduction.md b/lib/docs/introduction.md
@@ -0,0 +1,41 @@
+# Introduction
+
+[![crates.io](https://img.shields.io/crates/v/curies.svg)](https://crates.io/crates/curies)
+[![PyPI](https://img.shields.io/pypi/v/curies-rs)](https://pypi.org/project/curies-rs/)
+[![npm](https://img.shields.io/npm/v/@biopragmatics/curies)](https://www.npmjs.com/package/@biopragmatics/curies)
+
+A cross-platform Rust library for idiomatic conversion between URIs and compact URIs (CURIEs).
+
+Whether you're a developer looking to work with CURIEs (e.g. expand or compress) in your application, or a researcher seeking an efficient way to handle CURIEs, `curies` offers a suite of tools tailored to meet your needs.
+
+## 🔑 Key Features
+
+### ✨ CURIEs management
+
+- 🛠️ **Create** your custom converter
+- 📥 **Import** converters from JSON or JSON-LD context, with helper functions for popular converters, such as `get_obo_converter()`.
+- 🔗 **Expand**: CURIEs from their compressed form to a URI.
+- 🗜️ **Compress** URIs to CURIEs.
+
+### 📦️ Packaged for multiple interfaces
+
+This library is packaged for easy use across various interfaces and languages:
+
+- 🦀 **Rust developers**: available as a Rust crate `curies`.
+- 🐍 **Python programmers**: available as a Python pip package `curies-rs`.
+- 🌐 **Web developers**: available as a NPM package `@biopragmatics/curies`, 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
+
+## 🚀 Getting started
+
+Checkout the page most adapted to your use-case to get started.
+
+> 💡 **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/biopragmatics/curies.rs/issues) on our GitHub repository.