Merge pull request #37 from JPHutchins/docs/add-docs

Docs/add docs

.github/workflows/release.yaml

@@ -13,82 +13,114 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-    - run: git fetch --prune --unshallow --tags
+      - run: git fetch --prune --unshallow --tags
 
-    - run: pipx install poetry
+      - run: pipx install poetry
 
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: "3.x"
-        cache: 'poetry'
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: "poetry"
 
-    - run: poetry install
+      - run: poetry install
 
-    - run: poetry self add poetry-version-plugin
+      - run: poetry self add poetry-version-plugin
 
-    - run: poetry build
+      - run: poetry build
 
-    - name: Store the distribution packages
-      uses: actions/upload-artifact@v4
-      with:
-        name: python-package-distributions
-        path: dist/
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
 
   publish-to-pypi:
     name: Publish Python 🐍 distribution 📦 to PyPI
     needs:
-    - build
+      - build
 
     runs-on: ubuntu-latest
     environment:
       name: pypi
       url: https://pypi.org/p/${{ env.name }}
     permissions:
-      id-token: write  # IMPORTANT: mandatory for trusted publishing
+      id-token: write # IMPORTANT: mandatory for trusted publishing
 
     steps:
-    - name: Download all the dists
-      uses: actions/download-artifact@v4
-      with:
-        name: python-package-distributions
-        path: dist/
-    - name: Publish distribution 📦 to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
 
   github-release:
     name: >-
       Sign the Python 🐍 distribution 📦 with Sigstore
       and upload them to GitHub Release
     needs:
-    - publish-to-pypi
+      - publish-to-pypi
     runs-on: ubuntu-latest
 
     permissions:
-      contents: write  # IMPORTANT: mandatory for making GitHub Releases
-      id-token: write  # IMPORTANT: mandatory for sigstore
+      contents: write # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write # IMPORTANT: mandatory for sigstore
 
     steps:
-    - name: Download all the dists
-      uses: actions/download-artifact@v4
-      with:
-        name: python-package-distributions
-        path: dist/
-    - name: Sign the dists with Sigstore
-      uses: sigstore/[email protected]
-      with:
-        inputs: >-
-          ./dist/*.tar.gz
-          ./dist/*.whl
-    - name: Upload artifact signatures to GitHub Release
-      env:
-        GITHUB_TOKEN: ${{ github.token }}
-      # Upload to GitHub Release using the `gh` CLI.
-      # `dist/` contains the built packages, and the
-      # sigstore-produced signatures and certificates.
-      run: >-
-        gh release upload
-        '${{ github.ref_name }}' dist/**
-        --repo '${{ github.repository }}'
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Sign the dists with Sigstore
+        uses: sigstore/[email protected]
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+      - name: Upload artifact signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload
+          '${{ github.ref_name }}' dist/**
+          --repo '${{ github.repository }}'
+
+  publish-docs:
+    name: Publish documentation 📚 to GitHub Pages
+    needs:
+      - github-release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - run: git fetch --prune --unshallow --tags
+
+      - run: pipx install poetry
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: "poetry"
+
+      - run: poetry install --only doc
+
+      - name: Configure git for gh-pages
+        run: |
+          git config --global user.name "SMP Docs Bot"
+          git config --global user.email "[email protected]"
+
+      - name: Set release version
+        run: echo "GIT_TAG=${{ github.event.release.tag_name }}" >> $GITHUB_ENV
+
+      - name: Build and deploy documentation
+        run: poetry run mike deploy --push --update-aliases ${GIT_TAG} latest

.github/workflows/test-docs.yaml

@@ -0,0 +1,24 @@
+name: Test Docs Build
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: "poetry"
+
+      - run: poetry install --only doc
+
+      - run: poetry run mkdocs build

.gitignore

@@ -5,3 +5,4 @@ __pycache__
 .pytest_cache
 dist
 .tox
+site

README.md

@@ -15,6 +15,11 @@ If you need an SMP CLI application to interact with device firmware, then try
 
 `smp` is [distributed by PyPI](https://pypi.org/project/smp/) and can be installed with `poetry`, `pip`, and other dependency managers.
 
+## User Documentation
+
+Documentation is in the source code so that it is available to your editor.
+An online version is generated and available [here](https://jphutchins.github.io/smp/).
+
 ## Development Quickstart
 
 > Assumes that you've already [setup your development environment](#development-environment-setup).

docs/error.md

@@ -0,0 +1,3 @@
+# SMP V1 and V2 Errors
+
+::: smp.error

docs/exception.md

@@ -0,0 +1,3 @@
+# SMP Exceptions
+
+::: smp.exceptions

docs/file_management.md

@@ -0,0 +1,3 @@
+# File Management
+
+::: smp.file_management

docs/image_management.md

@@ -0,0 +1,3 @@
+# Image Management
+
+::: smp.image_management

docs/index.md

@@ -0,0 +1,3 @@
+# Simple Management Protocol (SMP)
+
+::: smp

docs/message.md

@@ -0,0 +1,5 @@
+# De/serialization and Validation
+
+::: smp.message
+    options:
+        filters: []

docs/os_management.md

@@ -0,0 +1,3 @@
+# OS Management
+
+::: smp.os_management

docs/packet.md

@@ -0,0 +1,5 @@
+# Packet en/de-coding and fragmentation/reassembly
+
+::: smp.packet
+    options:
+        show_if_no_docstring: false

docs/settings_management.md

@@ -0,0 +1,3 @@
+# Settings Management
+
+::: smp.settings_management

docs/shell_management.md

@@ -0,0 +1,3 @@
+# Shell Management
+
+::: smp.shell_management

docs/statistics_management.md

@@ -0,0 +1,3 @@
+# Statistics Management
+
+::: smp.statistics_management

docs/stylesheets/extra.css

@@ -0,0 +1,44 @@
+@import url('https://fonts.googleapis.com/css2?family=DM+Serif+Display:ital@0;1&family=Montserrat:ital,wght@0,100..900;1,100..900&display=swap');
+
+:root {
+    --md-default-bg-color: #f6e8d9;
+    --md-primary-fg-color: #80A69C;
+    --md-accent-fg-color: #80A69C;
+    --ic-dark-teal: #80A69C;
+    --ic-dark-lime: #BAC452;
+    --ic-light-lime: #b8c440;
+    --ic-extra-dark-lime: #939C04;
+    --ic-light-teal: #80A69C;
+    --ic-beige: #F6E8D9;
+    --cream: #f6e8d9;
+    --black: black;
+    --white: white;
+    --grey: grey;
+    --marin: #93bcb3;
+    --blue: #9bbdd5;
+    --purple: #c2aebe;
+    --yelow: #b8c440;
+    --pink: #d9b6a3;
+}
+
+.md-header {
+    color: #000000;
+    background-color: var(--marin);
+    font-family: 'Montserrat', sans-serif;
+}
+
+.md-header .md-header__topic {
+    color: #000000;
+    font-weight: 700;
+}
+
+.md-typeset h1 {
+    color: var(--ic-extra-dark-lime);
+    font-family: 'DM Serif Display', serif;
+    font-weight: 400;
+    font-size: 42px;
+}
+
+.md-nav__title {
+    color: #000000;
+}

docs/user/intercreate.md

@@ -0,0 +1,3 @@
+# Intercreate
+
+::: smp.user.intercreate

docs/zephyr_management.md

@@ -0,0 +1,3 @@
+# Zephyr Management
+
+::: smp.zephyr_management

mkdocs.yaml

@@ -0,0 +1,71 @@
+site_name: Simple Management Protocol (SMP)
+
+repo_name: JPHutchins/smp
+repo_url: https://github.com/JPHutchins/smp
+
+nav:
+  - Home: index.md
+  - File Management: file_management.md
+  - Image Management: image_management.md
+  - OS Management: os_management.md
+  - Settings Management: settings_management.md
+  - Shell Management: shell_management.md
+  - Statistics Management: statistics_management.md
+  - Zephyr Management: zephyr_management.md
+  - User Groups:
+      - Intercreate: user/intercreate.md
+  - Packets (USB/Serial): packet.md
+  - Errors: error.md
+  - Exceptions: exception.md
+  - De/Serialization: message.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_source: true
+            members_order: source
+            show_private_members: true
+            show_signature_annotations: true
+            show_if_no_docstring: true
+  - mike:
+      # These fields are all optional; the defaults are as below...
+      alias_type: symlink
+      redirect_template: null
+      deploy_prefix: ""
+      canonical_version: null
+      version_selector: true
+      css_dir: css
+      javascript_dir: js
+
+extra:
+  version:
+    provider: mike
+
+extra_css:
+  - stylesheets/extra.css
+
+theme:
+  name: material
+  palette:
+    primary: custom
+    accent: custom
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - footnotes
+  - meta
+  - toc:
+      permalink: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.snippets
+  - pymdownx.superfences