Merge pull request #5 from SFTtech/milo/sphinx-docs

docs: add initial docs structure using sphinx

Author: TheJJ

.github/workflows/ci.yml

@@ -61,6 +61,23 @@ jobs:
       - name: Run Ruff Format Check
         run: uv run ruff format --check
 
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+      - name: Run sphinx-build
+        run: uv run sphinx-build docs docs/_build
+  
   unit-tests:
     runs-on: ${{ matrix.os }}
     strategy:

README.md

@@ -56,3 +56,12 @@ Setup:
 uv sync
 uv run pre-commit install
 ```
+
+Build the documentation
+
+```bash
+# oneshot build
+uv run sphinx-build docs docs/_build
+# continous serving
+uv run sphinx-autobuild docs docs/_build
+```

docs/.gitignore

@@ -0,0 +1 @@
+/_build

docs/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
+from datetime import date
+
+project = "debmagic"
+copyright = f"{date.today().year}, Debmagic Authors"
+author = "Debmagic Authors"
+
+master_doc = "index"
+language = "en"
+
+extensions = [
+    "sphinx_copybutton",
+    "myst_parser",
+]
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build"]
+
+# html settings
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_context = {
+    "display_github": True,
+    "github_user": "SFTtech",
+    "github_repo": "debmagic",
+    "github_version": "main",
+    "conf_py_path": "/docs/",
+}

docs/develop/_changelog.md

@@ -0,0 +1,6 @@
+# Changelog
+
+```{include} ../../debian/changelog
+:relative-docs: docs/
+:relative-images:
+```

docs/develop/index.md

@@ -0,0 +1,7 @@
+# Contribute
+
+This section covers documentation relevant to developing and maintaining the debmagic
+codebase, and some guidelines for how you can contribute.
+
+```{toctree}
+```

docs/index.md

@@ -0,0 +1,23 @@
+# debmagic
+
+```{toctree}
+:hidden:
+:caption: Usage
+
+usage/getting-started.md
+usage/installation.md
+```
+
+```{toctree}
+:hidden:
+:caption: Development
+
+develop/index.md
+```
+
+```{toctree}
+:hidden:
+:caption: 📖 Reference
+
+develop/_changelog.md
+```

docs/usage/getting-started.md

@@ -0,0 +1,2 @@
+# Getting Started
+

docs/usage/installation.md

@@ -0,0 +1 @@
+# Installation

pyproject.toml

@@ -23,7 +23,21 @@ requires = ["setuptools>=77.0.0", "setuptools-scm"]
 build-backend = "setuptools.build_meta"
 
 [dependency-groups]
-dev = ["pytest>=9.0.1", "pytest-cov>=7.0.0", "ruff", "pre-commit", "mypy"]
+dev = [
+    { include-group = "docs" },
+    "pytest>=9.0.1",
+    "pytest-cov>=7.0.0",
+    "ruff",
+    "pre-commit",
+    "mypy",
+]
+docs = [
+    "sphinx>=8.2.3,<9",
+    "myst-parser>=4.0.1",
+    "sphinx-autobuild>=2025.8.25",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-rtd-theme>=3.0.2",
+]
 
 [tool.mypy]
 mypy_path = '$MYPY_CONFIG_FILE_DIR/src'