Extras

Building documentation

The documentation for SimpleBLE is built using Fumadocs, a Next.js-based documentation framework.

Prerequisites

• Node.js 20.9+ or Bun
• npm, pnpm, or bun package manager

Installation

First, install the dependencies:

cd <path-to-repository>/docs
npm install
# or
bun install

Development

To run the documentation site in development mode with hot reload:

npm run dev
# or
bun dev

The documentation will be available at http://localhost:3000.

Building for Production

To build the documentation for production:

npm run build
# or
bun run build

To preview the production build locally:

npm run start
# or
bun start

Content Structure

• Content files: Located in docs/content/docs/
• Components: Located in docs/src/components/
• API documentation: Generated using custom React components in docs/src/components/api/

Documentation is written in MDX (Markdown with JSX), allowing you to use React components within your documentation.

Release checklist

Before releasing a new version of the project, perform the following steps in order.

Prepare the release

1. Ensure content parity between all readmes and the documentation.

   • README.rst
   • LICENSE.md
   • simpleaible/README.md
   • simpledroidble/README.md
   • simplegoble/README.md
   • simplejavable/README.md
   • simplejsble/README.md
   • simplektble/README.md
   • simplepyble/README.md
   • simplernble/README.md
   • simplersble/README.md
   • simplesharpble/README.md

2. Update and review the release version in the following files:

   • VERSION
   • Cargo.toml (remove the -dev1 suffix)
   • Cargo.lock
   • docs/content/docs/changelog.mdx (add the actual release date)
   • simpleaible/pyproject.toml (remove the -dev1 suffix)

   If the release version differs from the development version, for example when releasing 1.2.0 from 1.1.1-dev1, also rename the changelog heading and search the repository for the old version with git grep to catch references such as migration guides.

3. Run the Hardware In The Loop tests listed below.

4. Run the pre-release checks from the repository root:

   ./scripts/check_version.sh
   cargo build
   (cd docs && npm run types:check && npm run build)

   Review the resulting diff and confirm that Cargo.lock contains the release version.

5. Commit the release changes to the repository.

6. Push the release commit to the remote repository without a tag.

7. Wait for the branch-triggered CI Main workflow to finish successfully. A main push publishes development packages: X.Y.Z-devN to crates.io and Maven Central, X.Y.Z.devN to PyPI, X.Y.Z-dev.N to NuGet, and X.Y.Z-devN to npm under the dev tag.

   Confirm that SimpleRsBLE, SimplePyBLE, SimpleAIBLE, SimpleJavaBLE, SimpleDroidBridge, SimpleDroidBLE, SimpleSharpBLE, SimpleJSBLE, SimpleRnBLE, and SimpleKtBLE all use the expected development version. If a fix is required, push the fix and wait for its workflow to finish before continuing. If a job fails for a reason unrelated to the release, such as an interrupted Android SDK download, use Re-run failed jobs on that run instead.

Tag and publish the release

8. Confirm that the latest commit on main is the exact commit whose CI Main workflow succeeded, then create an annotated tag:

   git tag -a vX.Y.Z -m "SimpleBLE vX.Y.Z release"

9. Push the tag to the remote repository. Tag-only pushes intentionally do not start CI Main; there is no workflow to cancel.

10. Create and publish a stable GitHub release for that tag. A draft does not trigger publication, and the release must not be marked as a prerelease.

11. Wait for the release-triggered CI Main workflow to finish. This workflow uploads the GitHub release artifacts and publishes the stable packages.

    • Do not cancel it, unpublish and republish the release, or run CI Main manually on the tag. Runs for the tag cancel each other. Editing the release notes is safe.
    • If a job fails, use Re-run failed jobs, never Re-run all jobs. PyPI, NuGet, and npm skip versions that already exist, but crates.io and Maven Central reject them, so repeating a publish job that already succeeded fails.

12. Verify the published release:

    • The GitHub release contains the expected artifacts and no filenames with a development suffix.
    • SimplePyBLE X.Y.Z is available on PyPI.
    • SimpleAIBLE X.Y.Z is available on PyPI.
    • SimpleRsBLE X.Y.Z is available and not yanked on crates.io.
    • SimpleJavaBLE X.Y.Z is available on Maven Central.
    • SimpleDroidBLE and SimpleDroidBridge X.Y.Z are available on Maven Central.
    • SimpleSharpBLE X.Y.Z is available on NuGet.
    • SimpleJSBLE X.Y.Z is available on npm under the latest tag.
    • SimpleRnBLE X.Y.Z is available on npm under the latest tag.
    • SimpleKtBLE X.Y.Z is available on Maven Central.

    Maven Central and NuGet can take 15 minutes or more to list a new version after its publish job succeeds.

13. Replace references to development builds outside this repository now that the stable packages are available, such as the SimplePyBLE version pinned by the Dongl quickstart on simpleble.org. Search sibling checkouts for .devN and -devN pins, and deploy any site that changes.

Start the next development version

14. Advance to the next development version in the following files:

    • VERSION (next version without a development suffix)
    • Cargo.toml (next version with a -dev1 suffix)
    • Cargo.lock (next version with a -dev1 suffix)
    • docs/content/docs/changelog.mdx (add an empty section for the next version)
    • simpleaible/pyproject.toml (next version with a -dev1 suffix)

15. Validate the development bump and documentation:

    cargo build
    (cd docs && npm run types:check && npm run build)

16. Commit and push the development-version bump.

17. Wait for the branch-triggered CI Main workflow to finish successfully and confirm that the new development packages were published to crates.io, PyPI, Maven Central, and NuGet with the expected -devN/.devN/-dev.N versions.

18. From the documentation root, run berth app deploy to deploy the documentation.

Hardware In The Loop - Recommended Tests

• Attempt connecting while already connected.
• Attempt disconnecting while not connected.

Documentation Structure Guide

When adding documentation for new components or language bindings, follow this standardized structure to ensure consistency and a high-quality onboarding experience:

1. Usage: Detail installation, system requirements, and how to include the library in a project (CMake, package managers, etc.).
2. Platform Notes: Document OS-specific behaviors, limitations, and quirks. This is critical for Bluetooth-related components.
3. Tutorial: Provide a narrative, step-by-step guide that takes the user from a basic "Hello World" (e.g., listing adapters) to more advanced interactions (scanning, connecting, reading/writing).
4. API Reference: Use the <ApiSection>, <ApiClass>, and <ApiMethod> components to provide technical details for every public class and method.
5. Examples: Provide a curated list of use-cases with descriptions and direct links to the source code in the repository.
6. FAQ: Address common questions, troubleshooting steps, and platform-specific nuances that don't fit in the tutorial.