Docusaurus Setup

.github/workflows/deploy.yml

@@ -0,0 +1,56 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    # Set the default working directory for all steps in this job
+    defaults:
+      run:
+        working-directory: ./docs/chiplib-docs
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/chiplib-docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Build website
+        run: npm run build
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/chiplib-docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-deploy.yml

@@ -0,0 +1,32 @@
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+      - develop
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./docs/chiplib-docs
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/chiplib-docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Test build website
+        run: npm run build

docs/chiplib-docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/chiplib-docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/chiplib-docs/docs/specifications/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Specifications",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "How ChipLib YAML files are formatted and the specifications around them"
+  }
+}

docs/chiplib-docs/docs/specifications/best-practices.md

@@ -0,0 +1,10 @@
+---
+sidebar_position: 7
+---
+
+# Best Practices
+
+1.  **Naming:** Use **Title Case** for `name` fields (e.g., "Conversion Rate"). Use **UPPER\_CASE** for `symbol` fields representing registers or enums.
+2.  **Binary Literals:** Use binary (`0b...`) for enum values and bitmasks to make the specific bit settings obvious.
+3.  **Documentation:** Use the `description` fields liberally. This text is propagated to the generated code (e.g., Doxygen comments) and is vital for the end-user.
+4.  **Resets:** Always verify that the `reset` value of a register matches the sum of its fields' defaults in the datasheet.

docs/chiplib-docs/docs/specifications/defaults.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 3
+---
+
+# Defaults
+
+The `defaults` block defines properties that apply to *all* registers unless explicitly overridden at the register or
+field level. This reduces repetition.
+
+| Field            |  Required   | Type               | Description                                      |
+|:-----------------|:-----------:|:-------------------|:-------------------------------------------------|
+| `register_width` |   **Yes**   | `Integer`          | The standard width of a register in bits.        |
+| `byte_order`     |   **Yes**   | `Enum`             | `big` (MSB first) or `little` (LSB first).       |
+| `access`         | Recommended | `List[AccessCode]` | Default read/write permissions (e.g., `[r, w]`). |
+
+**Example:**
+
+```yaml
+defaults:
+  register_width: 16
+  byte_order: big
+  access: [ r, w ]
+```
+
+:::tip Other Fields
+
+Any other field that would typically go in the `fields:` section can be included. For example, if a device's registers
+all reset to the same value, the `reset:` field could be included in the `defaults:`.
+
+:::

docs/chiplib-docs/docs/specifications/enums.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 4
+---
+
+# Enums
+
+Enumerations (`enums`) define named states for bit-fields. They are defined globally to allow reuse across multiple
+registers.
+
+### Enum Object Structure
+
+| Field    | Required | Type             | Description                                                                 |
+|:---------|:--------:|:-----------------|:----------------------------------------------------------------------------|
+| `symbol` | **Yes**  | `String`         | The programmatic name for the Enum type. Must be PascalCase or UPPER\_CASE. |
+| `values` | **Yes**  | `List[ValueObj]` | A list of named values belonging to this enum.                              |
+
+### Enum Value Object
+
+| Field         |  Required   | Type      | Description                                                                                     |
+|:--------------|:-----------:|:----------|:------------------------------------------------------------------------------------------------|
+| `name`        |   **Yes**   | `String`  | The human-readable name of the state. Used to generate the enum member name.                    |
+| `value`       |   **Yes**   | `Integer` | The raw integer value of the state. Supports `0x` for hexadecimal, `0b` for binary, or decimal. |
+| `description` | Recommended | `String`  | Documentation for this specific state.                                                          |
+
+**Example:**
+
+```yaml
+enums:
+  - symbol: Gain
+    values:
+      - name: Gain 1x
+        value: 0b00
+        description: "Standard gain setting."
+      - name: Gain 8x
+        value: 0b11
+        description: "High sensitivity mode."
+```

docs/chiplib-docs/docs/specifications/fields.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 6
+---
+
+# Fields
+
+Fields define the bit-packing layout within a register.
+
+## Field Object Structure
+
+| Field         |  Required   | Type               | Description                                                                         |
+|:--------------|:-----------:|:-------------------|:------------------------------------------------------------------------------------|
+| `symbol`      |   **Yes**   | `String`           | The programmatic name for the field (e.g., `EN`).                                   |
+| `bits`        |   **Yes**   | `List[Integer]`    | The bit range as `[high, low]` (e.g., `[7, 7]` or `[15, 12]`).                      |
+| `name`        | Recommended | `String`           | Full name of the field.                                                             |
+| `description` | Recommended | `String`           | Documentation for the field.                                                        |
+| `access`      |     No      | `List[AccessCode]` | Overrides the default register access.                                              |
+| `enum`        |     No      | `String`           | The `symbol` of a global Enum to link to this field.                                |
+| `reset`       | Recommended | `String` or `Int`  | The reset value for *this specific field*. Can be a number or an Enum Value `name`. |
+| `format`      |     No      | `FormatObj`        | Defines data representation (signed/unsigned) and units.                            |
+
+### Access Codes
+
+| Code    | Meaning                           |
+|:--------|:----------------------------------|
+| `r`     | Readable.                         |
+| `w`     | Writable.                         |
+| `woset` | Write-One-to-Set (Self-clearing). |
+| `w1c`   | Write-1-to-Clear.                 |
+| `rc`    | Read-to-Clear.                    |
+
+### Format Object Structure
+
+The `format` block is used to describe the **raw data representation** and provide **documentation units**. It does
+*not* generate scaling logic.
+
+| Field            | Required | Type     | Description                                                                                                                                                                                                                                                                                                 |
+|:-----------------|:--------:|:---------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `representation` | **Yes**  | `String` | Can be one of the following options:<br></br>1. `us`: Unsigned e.g. uint8_t or uint32_t<br></br>2. `tc`: Two's Compliment e.g. int8_t or int32_t, sign extended<br></br>3. `sm`: Sign Magnitude e.g. MSB is the sign bit<br></br>4. `bd`: Binary Coded Decimal e.g. Each 4 bits represent a digit from 0-9. |
+| `unit`           |    No    | `String` | The real-world unit of measurement (e.g., `"Celsius"`, `"Volts"`).                                                                                                                                                                                                                                          |
+| `scale`          |    No    | `Float`  | The magnitude scalar applied to the units. For example, `0.001` would be used in conjunction with `unit: "Celsius"` to denote **millicelsius**.                                                                                                                                                             |
+
+**Example (Field with Format):**
+
+```yaml
+- symbol: TEMP
+  bits: [ 15, 4 ]
+  access: [ r ]
+  description: "Temperature result."
+  format:
+    representation: tc
+    unit: "Celsius"
+    scale: 1.0
+```

docs/chiplib-docs/docs/specifications/metadata.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 2
+---
+
+# Metadata
+
+These top level fields identify the device and provide context for documentation generators.
+
+| Field          |  Required   | Type           | Description                                                                | Example                      |
+|:---------------|:-----------:|:---------------|:---------------------------------------------------------------------------|:-----------------------------|
+| `chip`         |   **Yes**   | `String`       | The canonical part number or model name. Used for class naming.            | `TMP1075N`                   |
+| `manufacturer` |   **Yes**   | `String`       | The name of the silicon vendor.                                            | `Texas Instruments`          |
+| `description`  | Recommended | `String`       | A brief summary of the device's function.                                  | `Digital Temperature Sensor` |
+| `interface`    |   **Yes**   | `List[String]` | Supported communication protocols.                                         | `[I2C, SMBus]`               |
+| `revision`     |     No      | `String`       | If there are multiple silicon revisions that have different register maps. | `A`                          |
+
+## Chip Notes
+
+The chip name should not include the footprint portion of the device's part number. For example:
+
+**TMP1075DR** - SOIC 8 package
+
+**TMP1075DSGR** - WSON 9 package
+
+Would both fall under the TMP1075.yaml file as there is no register difference. However,
+
+**TMP1075NDRLR** - SOT-563 package
+
+Would get its own TMP1075N.yaml as it has a slightly different register map than the TMP1075 no N. The register map
+difference is what requires the different file, not the packaging difference.
+
+:::note Package Suffixes
+
+The package portion of part numbers should be left off, such as both the TMP1075**DR** and TMP1075**DSGR** parts
+drop their suffix to be combined into just TMP1075.yaml.
+
+:::
+
+## Interface Notes
+
+The interface can be a variety of standard interface options such as:
+
+* `I2C`
+* `SPI`
+* `UART`
+* `One Wire`
+* `SMBus`
+* `Quad SPI`
+* etc.
+
+The interface name should be the widely used, condensed (`I2C` instead of `Inter-Integrated Circuit`) name for the bus.
+If a device has multiple communication protocols, all should be listed.
+
+## Revision Notes
+
+The `revision` field should **not** be included unless silicon revisions affect the register map for simplicity.

docs/chiplib-docs/docs/specifications/overview.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+A ChipLib YAML file represents a single integrated circuit (IC) or IP block. The file is structured into four primary sections:
+
+1.  **Metadata:** Top-level information identifying the chip.
+2.  **Defaults:** Global settings applied to registers unless overridden.
+3.  **Enums:** Shared enumeration definitions for bit-fields.
+4.  **Registers:** The complete memory map definition.
+
+### Example Skeleton
+
+```yaml
+chip: <String>
+manufacturer: <String>
+description: <String>
+interface: <List[String]>
+
+defaults:
+  register_width: <Integer>
+  byte_order: <"big" | "little">
+  access: <List[AccessCode]>
+
+enums:
+  - symbol: <String>
+    values: [...]
+
+registers:
+  - address: <Integer>
+    symbol: <String>
+    fields: [...]
+````