Merge pull request #99 from UpstreamDataInc/dev_gh_pages

Update documentation

.github/workflows/gh-pages.yml

@@ -11,6 +11,9 @@ on:
       - "pyproject.toml"
       - "docs/**"
 
+env:
+  SITE_URL: https://upstreamdatainc.github.io/goosebit
+
 jobs:
   publish:
     runs-on: ubuntu-latest
@@ -33,4 +36,4 @@ jobs:
         run: poetry install --no-root --with docs
 
       - name: Deploy website
-        run: poetry run mkdocs gh-deploy
+        run: poetry run mkdocs gh-deploy --theme material

.pre-commit-config.yaml

@@ -7,6 +7,12 @@ repos:
     hooks:
       - id: trailing-whitespace
       - id: check-yaml
+        name: check-yaml for mkdocs.yml
+        files: ^mkdocs\.yml$
+        args: [--unsafe]
+      - id: check-yaml
+        name: check-yaml for other YAML files
+        exclude: ^mkdocs\.yml$
       - id: check-added-large-files
   - repo: https://github.com/psf/black
     rev: 24.8.0

docs/development.md

@@ -0,0 +1,82 @@
+# Development
+
+---
+
+### Installation
+
+Install development dependencies using [Poetry](https://python-poetry.org/):
+
+```shell
+poetry install --with dev
+```
+
+gooseBit also has dependencies for documentation and tests, you can install them all with:
+
+```shell
+poetry install --with dev,docs,tests
+```
+
+You can also just install all extras with:
+
+```shell
+poetry install --all-extras
+```
+
+## Development
+
+### Code formatting and linting
+
+Code is formatted using different tools
+
+-   black and isort for `*.py`
+-   biomejs for `*.js`, `*.json`
+-   prettier for `*.html`, `*.md`, `*.yml`, `*.yaml`
+-   djlint for `*.html.jinja`
+
+Code is linted using different tools as well
+
+-   flake8 for `*.py`
+-   biomejs for `*.js`
+-   djlint for `*.html.jinja`
+
+Best to have pre-commit install git hooks that run all those tools before a commit:
+
+```bash
+poetry run pre-commit install
+```
+
+To manually apply the hooks to all files use:
+
+```bash
+pre-commit run --all-files
+```
+
+### Testing
+
+Tests are implemented using pytest. To run all tests
+
+```bash
+poetry run pytest
+```
+
+### Structure
+
+The structure of gooseBit is as follows:
+
+-   `api`: Files for the API.
+-   `ui`: Files for the UI.
+    -   `bff`: Backend for frontend API.
+    -   `static`: Static files.
+    -   `templates`: Jinja2 formatted templates.
+    -   `nav`: Navbar handler.
+-   `updater`: DDI API handler and device update manager.
+-   `updates`: SWUpdate file parsing.
+-   `realtime`: Realtime API functionality with websockets.
+-   `auth`: Authentication functions.
+-   `models`: Database models.
+-   `db`: Database config and initialization.
+-   `schema`: Pydantic models used for API type hinting.
+-   `permissions`: Permission handling and permission enums.
+-   `settings`: Settings loader and handler.
+-   `telemetry`: Telemetry data handlers.
+-   `routes`: Routes for a giving endpoint, including the router.

docs/index.md

@@ -1,30 +1,11 @@
-# gooseBit
-
-<img src="docs/img/goosebit-logo.png" style="width: 100px; height: 100px; display: block;">
+# Home
 
 ---
 
-A simplistic, opinionated remote update server implementing hawkBit™'s [DDI API](https://eclipse.dev/hawkbit/apis/ddi_api/).
-
-## Quick Start
-
-### Installation
-
-1. Install dependencies using [Poetry](https://python-poetry.org/):
-    ```bash
-    poetry install
-    ```
-2. Launch gooseBit:
-    ```bash
-    python main.py
-    ```
-
-### Initial Configuration
-
-Before running gooseBit for the first time, update the default credentials in `settings.yaml`. The default login for testing purposes is:
+### What is gooseBit?
 
--   **Username:** `[email protected]`
--   **Password:** `admin`
+A simplistic, opinionated remote update server implementing hawkBit™'s [DDI API](https://eclipse.dev/hawkbit/apis/ddi_api/),
+designed to make remote updates of embedded devices easier.
 
 ## Assumptions
 
@@ -68,60 +49,3 @@ Devices can be pinned to their current software version, preventing any updates
 ### Real-time Update Logs
 
 While updates are in progress, gooseBit captures real-time logs, which are accessible through the device repository.
-
-## Development
-
-### Code formatting and linting
-
-Code is formatted using different tools
-
--   black and isort for `*.py`
--   biomejs for `*.js`, `*.json`
--   prettier for `*.html`, `*.md`, `*.yml`, `*.yaml`
-
-Code is linted using different tools as well
-
--   flake8 for `*.py`
--   biomejs for `*.js`
-
-Best to have pre-commit install git hooks that run all those tools before a commit:
-
-```bash
-poetry run pre-commit install
-```
-
-To manually apply the hooks to all files use:
-
-```bash
-pre-commit run --all-files
-```
-
-### Testing
-
-Tests are implemented using pytest. To run all tests
-
-```bash
-poetry run pytest
-```
-
-### Structure
-
-The structure of gooseBit is as follows:
-
--   `api`: Files for the API.
--   `ui`: Files for the UI.
-    -   `bff`: Backend for frontend API.
-    -   `static`: Static files.
-    -   `templates`: Jinja2 formatted templates.
-    -   `nav`: Navbar handler.
--   `updater`: DDI API handler and device update manager.
--   `updates`: SWUpdate file parsing.
--   `realtime`: Realtime API functionality with websockets.
--   `auth`: Authentication functions.
--   `models`: Database models.
--   `db`: Database config and initialization.
--   `schema`: Pydantic models used for API type hinting.
--   `permissions`: Permission handling and permission enums.
--   `settings`: Settings loader and handler.
--   `telemetry`: Telemetry data handlers.
--   `routes`: Routes for a giving endpoint, including the router.

docs/quick_start.md

@@ -0,0 +1,24 @@
+# Quick Start
+
+---
+
+### Installation
+
+#### Install dependencies using [Poetry](https://python-poetry.org/):
+
+```shell
+poetry install
+```
+
+#### Launch gooseBit:
+
+```shell
+python main.py
+```
+
+### Initial Configuration
+
+Before running gooseBit for the first time, update the default credentials in `settings.yaml`. The default login for testing purposes is:
+
+-   **Username:** `[email protected]`
+-   **Password:** `admin`

mkdocs.yml

@@ -1,7 +1,27 @@
 repo_url: https://github.com/UpstreamDataInc/goosebit
 repo_name: gooseBit
 site_name: gooseBit
+site_url: !ENV SITE_URL
 theme:
   name: material
   logo: img/goosebit-logo.svg
   favicon: img/goosebit-logo.svg
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to auto mode
+nav:
+  - Home: index.md
+  - Quick Start: quick_start.md
+  - Development: development.md