Improve CLI subcommand organisation and convert docs to Material for Mkdocs

.pre-commit-config.yaml

@@ -31,19 +31,6 @@ repos:
     hooks:
       - id: prettier
 
-  - repo: https://github.com/thclark/pre-commit-sphinx
-    rev: 0.0.3
-    hooks:
-      - id: build-docs
-        language_version: python3
-        additional_dependencies:
-          - "poetry==1.2.0b2"
-          - "Sphinx>=5,<8"
-          - "sphinx-rtd-theme>=1,<2"
-          - "sphinx-tabs>=3,<4"
-          - "sphinx-toolbox>=3"
-          - "git+https://github.com/octue/octue-sdk-python.git@main"
-
   - repo: https://github.com/windpioneers/pre-commit-hooks
     rev: 0.0.5
     hooks:

.readthedocs.yaml

@@ -1,16 +1,12 @@
-# Read the Docs configuration file for Sphinx projects
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: "ubuntu-24.04"
   tools:
-    python: "3.10"
-
-sphinx:
-  configuration: docs/source/conf.py
+    python: "3.13"
+  jobs:
+    pre_install:
+      - pip install -r docs/requirements.txt
 
-python:
-  install:
-    - requirements: docs/requirements.txt
+mkdocs:
+  configuration: mkdocs.yml

docs/contributing.md → CONTRIBUTING.md

@@ -84,36 +84,12 @@ You can run pre-commit hooks without making a commit, too, like:
 pre-commit run black --all-files
 ```
 
-or
-
-```
-# -v gives verbose output, useful for figuring out why docs won't build
-pre-commit run build-docs -v
-```
-
 ## Documentation
 
-### Building documents automatically
-
-The documentation will build automatically in a pre-configured environment when you make a commit.
-
-In fact, the way `pre-commit` works, you won't be allowed to make the commit unless the documentation builds. This way
-we avoid getting broken documentation pushed to the main repository on any commit so we can rely on builds working.
-
-### Building documents manually
-
-**If you did need to build the documentation**
-
-Install `doxygen`. On a mac, that's `brew install doxygen`; other systems may differ.
-
-Install sphinx and other requirements for building the docs:
+To serve the docs locally, run:
 
 ```
-pip install -r docs/requirements.txt
+mkdocs serve
 ```
 
-Run the build process:
-
-```
-sphinx-build -b html docs/source docs/html
-```
+This makes the docs available on `localhost` via a hot-reloading server

README.md

@@ -6,7 +6,7 @@
 [![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10961975.svg)](https://doi.org/10.5281/zenodo.10961975)
 
-# Octue Python SDK <img src="./docs/source/images/213_purple-fruit-snake-transparent.gif" alt="Purple Fruit Snake" width="100"/></span>
+# Octue Python SDK <img src="./docs/images/213_purple-fruit-snake-transparent.gif" alt="Purple Fruit Snake" width="100"/></span>
 
 The python SDK for running [Octue](https://octue.com) data services, digital twins, and applications - get faster data
 groundwork so you have more time for the science!
@@ -36,30 +36,20 @@ octue --help
 ```text
 Usage: octue [OPTIONS] COMMAND [ARGS]...
 
-  The CLI for the Octue SDK. Use it to start an Octue data service or digital
-  twin locally or run an analysis on one locally.
+  The CLI for Octue SDKs and APIs, most notably Twined.
 
   Read more in the docs: https://octue-python-sdk.readthedocs.io/en/latest/
 
 Options:
-  --id UUID                       UUID of the analysis being undertaken. None
-                                  (for local use) will cause a unique ID to be
-                                  generated.
   --logger-uri TEXT               Stream logs to a websocket at the given URI.
   --log-level [debug|info|warning|error]
                                   Log level used for the analysis.  [default:
                                   info]
-  --force-reset / --no-force-reset
-                                  Forces a reset of analysis cache and outputs
-                                  [For future use, currently not implemented]
-                                  [default: force-reset]
   --version                       Show the version and exit.
   -h, --help                      Show this message and exit.
 
 Commands:
-  deploy  Deploy a python app to the cloud as an Octue service or digital...
-  run     Run an analysis on the given input data using an Octue service...
-  start   Start an Octue service or digital twin locally as a child so it...
+  twined  The Twined CLI.
 ```
 
 ## Deprecated code
@@ -95,4 +85,4 @@ python3 -m unittest
 
 ## Contributing
 
-Take a look at our [contributing](/docs/contributing.md) page.
+Take a look at our [contributing](/CONTRIBUTING.md) page.