switch to monorepo

introduce supplemental docs (using mkdocs) and WIP examples (incomplete at this time)

migrate to using [just](https://just.systems) as a task runner and utilize it in CI jobs.

.config/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    # rust: latest
+    python: latest
+
+mkdocs:
+  configuration: docs/mkdocs.yml
+
+
+# Optionally declare the Python requirements required to build your docs
+
+python:
+  install:
+    - requirements: docs/requirements.txt

.config/cliff.toml

@@ -0,0 +1,144 @@
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+# template for the changelog header
+header = """
+# Changelog\n
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- markdownlint-disable MD024 -->\n
+"""
+# template for the changelog body
+# https://keats.github.io/tera/docs/#introduction
+body = """
+{%- macro remote_url() -%}
+  https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
+{%- endmacro -%}
+{%- set UNRELEASED = "Unreleased" -%}
+{%- set init_commit = "f8863cc36d66708bfa0fb2fb1a219c7b2f97f7d6" -%}
+{%- set this_version = UNRELEASED -%}
+
+{% if version -%}
+    {%- set this_version = version | trim_start_matches(pat="v") -%}
+    ## [{{ this_version }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+    {%- if message %}
+
+        > {{ message }}
+    {%- endif %}
+{% else -%}
+    ## [{{ UNRELEASED }}]{% if previous and previous.timestamp %} - {{ previous.timestamp | date(format="%Y-%m-%d") }} to present{% endif %}
+{% endif -%}
+
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits %}
+        - {{ commit.message | split(pat="\n") | first | upper_first | trim }}\
+            {% if commit.remote.username %} by @{{ commit.remote.username }}{%- endif -%}
+            {% if commit.remote.pr_number %} in \
+            [#{{ commit.remote.pr_number }}]({{ self::remote_url() }}/pull/{{ commit.remote.pr_number }})
+            {%- else %} in \
+            [`{{ commit.id | truncate(length=7, end="") }}`]({{ self::remote_url() }}/commit/{{commit.id }})
+            {%- endif -%}
+    {% endfor %}
+{% endfor -%}
+
+{% set last_commit = "HEAD" -%}
+{%- set first_commit = init_commit -%}
+{% if version -%}
+    {%- set last_commit = version -%}
+    {%- if previous and previous.version -%}
+        {%- set first_commit = previous.version -%}
+    {%- endif -%}
+{%- endif %}
+[{{ this_version }}]: {{ self::remote_url() }}/compare/{{ first_commit }}...{{ last_commit }}
+
+Full commit diff: [`{% if previous.version -%}
+    {{ first_commit }}
+{%- else -%}
+    {{ init_commit | truncate(length=7, end="") }}
+{%- endif %}...{{ last_commit }}`][{{ this_version }}]
+{% if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 %}
+  ## New Contributors
+{%- endif -%}
+
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+  * @{{ contributor.username }} made their first contribution
+    {%- if contributor.pr_number %} in \
+      [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+    {%- endif %}
+{%- endfor %}\n
+"""
+# template for the changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+# remove the leading and trailing whitespace from the templates
+trim = true
+# The file path for output. This can be overridden with `--output` CLI arg
+# output = "CHANGELOG.md"
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# filter out the commits that are not conventional
+filter_unconventional = false
+# regex for preprocessing the commit messages
+commit_preprocessors = [
+    # remove issue numbers from commits
+    { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "" },
+]
+# regex for parsing and grouping commits
+commit_parsers = [
+    { field = "github.pr_labels", pattern = "breaking", group = "<!-- 0 --> 💥 Breaking changes" },
+    { field = "github.pr_labels", pattern = "breaking-change", group = "<!-- 0 --> 💥 Breaking changes" },
+    { field = "github.pr_labels", pattern = "feature", group = "<!-- 1 --> 🚀 Added" },
+    { field = "github.pr_labels", pattern = "enhancement", group = "<!-- 1 --> 🚀 Added" },
+    { field = "github.pr_labels", pattern = "deprecated", group = "<!-- 2 --> 🚫 Deprecated" },
+    { field = "github.pr_labels", pattern = "removed", group = "<!-- 3 --> 🗑️ Removed" },
+    { field = "github.pr_labels", pattern = "bug", group = "<!-- 4 --> 🛠️ Fixed" },
+    { field = "github.pr_labels", pattern = "security", group = "<!-- 5 --> 🔐 Security" },
+    { field = "github.pr_labels", pattern = "dependencies", group = "<!-- 6 --> 📦 Dependency updates" },
+    { field = "github.pr_labels", pattern = "test", group = "<!-- 7 -->🚦 Tests"},
+    { field = "github.pr_labels", pattern = "tests", group = "<!-- 7 -->🚦 Tests"},
+    { field = "github.pr_labels", pattern = "documentation", group = "<!-- 8 --> 📝 Documentation" },
+    { field = "github.pr_labels", pattern = "refactor", group = "<!-- 9 --> 🗨️ Changed" },
+    { field = "github.pr_labels", pattern = "skip-changelog", skip = true },
+    { field = "github.pr_labels", pattern = "no-changelog", skip = true },
+    { field = "github.pr_labels", pattern = "invalid", skip = true },
+    # The order of parsers matters. Put rules for PR labels first to prioritize PR labels.
+    { message = "^[a|A]dd", group = "<!-- 1 --> 🚀 Added" },
+    { message = "^[s|S]upport", group = "<!-- 1 --> 🚀 Added" },
+    { message = "^.*: support", group = "<!-- 1 --> 🚀 Added" },
+    { message = "^.*: add", group = "<!-- 1 --> 🚀 Added" },
+    { message = "^.*: deprecated", group = "<!-- 2 --> 🚫 Deprecated" },
+    { message = "[d|D]eprecate", group = "<!-- 2 --> 🚫 Deprecated" },
+    { message = "[t|T]ests", group = "<!-- 7 -->🚦 Tests"},
+    { message = "[r|R]emove", group = "<!-- 3 --> 🗑️ Removed" },
+    { message = "^.*: remove", group = "<!-- 3 --> 🗑️ Removed" },
+    { message = "^.*: delete", group = "<!-- 3 --> 🗑️ Removed" },
+    { message = "^[f|F]ix", group = "<!-- 4 --> 🛠️ Fixed" },
+    { message = "^.*: fix", group = "<!-- 4 --> 🛠️ Fixed" },
+    { message = "^.*: secure", group = "<!-- 5 --> 🔐 Security" },
+    { message = "[s|S]ecure", group = "<!-- 5 --> 🔐 Security" },
+    { message = "[s|S]ecurity", group = "<!-- 5 --> 🔐 Security" },
+    { message = "^.*: security", group = "<!-- 5 --> 🔐 Security" },
+    { message = "doc", group = "<!-- 8 --> 📝 Documentation" },
+    { message = "docs", group = "<!-- 8 --> 📝 Documentation" },
+    { message = "documentation", group = "<!-- 8 --> 📝 Documentation" },
+    { message = "[r|R]efactor", group = "<!-- 9 --> 🗨️ Changed" },
+    { field = "github.pr_labels", pattern = ".*", group = "<!-- 9 --> 🗨️ Changed" },
+    { message = "^.*", group = "<!-- 9 --> 🗨️ Changed" },
+]
+# filter out the commits that are not matched by commit parsers
+filter_commits = true
+# sort the tags topologically
+topo_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "oldest"
+
+# [remote.github]
+# owner = "cpp-linter"
+# repo = "cpp-linter-rs"

.config/nextest.toml

@@ -0,0 +1,22 @@
+# required minimum nextest version
+nextest-version = "0.9.77"
+
+[profile.default]
+# A profile to run most tests, except tests that run longer than 10 seconds
+default-filter = "all()"
+
+# This will flag any test that runs longer than 10 seconds. Useful when writing new tests.
+slow-timeout = "10s"
+
+[profile.ci]
+# A profile to run only tests that use clang-tidy and/or clang-format
+# NOTE: This profile is intended to keep CI runtime low. Locally, use default or all profiles
+
+# This is all tests in tests/ folder + unit test for --extra-args.
+default-filter = "all()"
+
+# show wich tests were skipped
+status-level = "skip"
+
+# show log output from each test
+failure-output = "immediate-final"

.github/dependabot.yml

@@ -16,8 +16,17 @@ updates:
   - package-ecosystem: cargo
     directory: /
     schedule:
-      interval: "daily"
+      interval: "weekly"
     groups:
       cargo:
         patterns:
           - "*"
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: "weekly"
+    groups:
+      pip:
+        patterns:
+          - "*"

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'lib/**'
+      - Cargo.toml
+      - '*.md'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'lib/**'
+      - Cargo.toml
+      - '*.md'
+
+jobs:
+  supplemental:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install cargo-binstall
+        uses: cargo-bins/cargo-binstall@main
+      - name: Install Just
+        run: cargo binstall -y just
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install -r docs/requirements.txt
+      - run: just docs-build
+      - name: Save docs build as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          path: docs/site
+          name: supplemental-docs
+
+  api:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-binstall
+        uses: cargo-bins/cargo-binstall@main
+      - name: Install Just
+        run: cargo binstall -y just
+      - run: just docs-rs
+      - name: save docs as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-docs
+          path: target/doc
+

.github/workflows/tests.yml

@@ -0,0 +1,59 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'lib/**'
+      - '!lib/README.md'
+      - Cargo.toml
+  pull_request:
+    branches: [main]
+    paths:
+      - 'lib/**'
+      - '!lib/README.md'
+      - Cargo.toml
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-binstall
+        uses: cargo-bins/cargo-binstall@main
+      - name: Install Just
+        run: cargo binstall -y just
+      - name: Cache deps
+        uses: actions/cache@v4
+        with:
+          path: ~/.cargo
+          key: cargo-lib-${{ hashFiles('lib/src/**', 'lib/Cargo.toml') }}
+      - run: just lint
+
+  test:
+    needs: [lint]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+      - name: Install cargo-binstall
+        uses: cargo-bins/cargo-binstall@main
+      - name: Install Just
+        run: cargo binstall -y just cargo-nextest cargo-llvm-cov
+      - name: Cache deps
+        uses: actions/cache@v4
+        with:
+          path: ~/.cargo
+          key: cargo-lib-${{ hashFiles('lib/src/**', 'lib/Cargo.toml') }}
+      - run: rustup component add llvm-tools-preview
+        # this enables a tool (for default toolchain) needed to measure code coverage.
+      - name: Run tests and generate reports
+        run: just test ci lcov
+      - uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: lcov.info
+          fail_ci_if_error: true

.gitignore

@@ -21,3 +21,10 @@ Cargo.lock
 
 # .vscode settings
 .vscode/
+
+# coverage output
+coverage.json
+lcov.info
+
+# supplemental docs build
+docs/site/

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- markdownlint-disable MD024 -->