Add Python documentation [Sphinx-Hatch]

.github/workflows/action.yml

@@ -167,12 +167,11 @@ jobs:
       with:
         toolchain: nightly
         override: true
-        components: rust-docs
     - name: Build docs
-      run: cargo doc
+      run: pip install hatch && hatch run dev:build-doc
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3
       if: ${{ github.ref == 'refs/heads/master' }}
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./target/doc
+        publish_dir: ./docs/build/html

docs/source/conf.py

@@ -0,0 +1,38 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import bluerobotics_navigator
+
+project = 'bluerobotics-navigator'
+release = "0.0.0" # todo: navigator.__version__
+version = release
+
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.napoleon',
+    'sphinx_rtd_theme',
+]
+
+autosummary_generate = True
+autosummary_imported_members = True
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_logo = "https://upload.wikimedia.org/wikipedia/commons/1/12/Bluerobotics-logo.svg"

docs/source/index.rst

@@ -0,0 +1,46 @@
+.. extension documentation master file, created by
+   sphinx-quickstart on Mon Jun 19 15:02:05 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+BlueRobotics's Navigator Library
+=====================================
+
+This library serves as the entry point for embedding applications using Python on Blue Robotics's Navigator_.
+
+The Navigator board has the Raspberry Pi HAT form factor, which allows you to easily attach it to a Raspberry Pi 4 board. Then you can unleash the power of Navigator to develop new solutions or interact with your ROV hardware.
+
+The board offers the following capabilities:
+
+Control:
+
+- LEDs
+
+- PWM (Pulse Width Modulation) with 16 channels
+
+Measurements:
+
+- ADC (Analog Digital Converter) entries
+
+- Magnetic field
+
+- Acceleration
+
+- Angular velocity
+
+- Temperature
+
+- Pressure
+
+Currently, it supports **armv7** and **aarch64** architectures, which are the official defaults for BlueOS_.
+However, despite using the embedded-hal concept, new ports can be added as long as the platform matches the hardware design and specifications.
+
+For more information, including installation instructions, schematics, and hardware specifications, please check the navigator hardware setup guide_.
+
+.. _Navigator: https://bluerobotics.com/store/comm-control-power/control/navigator/
+.. _BlueOS: https://docs.bluerobotics.com/ardusub-zola/software/onboard/BlueOS-1.1/
+.. _guide: https://bluerobotics.com/learn/navigator-hardware-setup/#introduction
+
+.. automodule:: bluerobotics_navigator
+   :members:
+   :undoc-members:

pyproject.toml

@@ -13,6 +13,7 @@ classifiers = [
 ]
 description = "This package serves as the entry point for embedded applications using Python on Blue Robotics's Navigator"
 readme = "README.md"
+dynamic = ["version"]
 
 [project.urls]
 Homepage = "https://bluerobotics.com/store/comm-control-power/control/navigator/"
@@ -21,3 +22,17 @@ Repository = "https://github.com/bluerobotics/navigator-lib"
 
 [tool.maturin]
 features = ["python"]
+
+[tool.hatch.envs.dev]
+dependencies = [
+    "maturin >=1.0.1",
+    "sphinx >=6.2.1",
+    "sphinx-rtd-theme >=1.2.2",
+    "sphinxcontrib-napoleon >=0.7",
+    "sphinx-pyproject >=0.1.0",
+    "ziglang >=0.10.1",
+]
+
+[tool.hatch.envs.dev.scripts]
+install = "maturin develop"
+build-doc = "install && sphinx-build ./docs/source docs/_build"