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.rst
   • simplepyble/README.rst
   • simplersble/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)

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 X.Y.Z.devN to PyPI.

   Confirm that SimpleRsBLE, SimplePyBLE, and SimpleAIBLE all use the expected development version. If a fix is required, push the fix and wait for its workflow to finish before continuing.

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. Do not cancel it. This workflow uploads the GitHub release artifacts and publishes the stable packages.

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.

Start the next development version

13. 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)

14. Validate the development bump and documentation:

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

15. Commit and push the development-version bump.

16. Wait for the branch-triggered CI Main workflow to finish successfully and confirm that the new development packages were published with the expected -devN/.devN versions.

17. From the documentation root, run minion 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.