diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 391938ef..1fd90c54 100644 --- a/.github/workflows/gh-pages.yml +++ b/.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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 4e563df1..ff60b207 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..ec7c216f --- /dev/null +++ b/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. diff --git a/docs/index.md b/docs/index.md index 48307461..adedaa75 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,30 +1,11 @@ -# gooseBit - - +# 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:** `admin@goosebit.local` -- **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. diff --git a/docs/quick_start.md b/docs/quick_start.md new file mode 100644 index 00000000..30aef4e3 --- /dev/null +++ b/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:** `admin@goosebit.local` +- **Password:** `admin` diff --git a/mkdocs.yml b/mkdocs.yml index 13b04c9f..a35b94ea 100644 --- a/mkdocs.yml +++ b/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