docs: build documentation with sphinx

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+env:
+  TASK_X_REMOTE_TASKFILES: 1
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        env:
+          BRANCH: ${{ github.head_ref || github.ref_name }}
+          GH_TOKEN: ${{ github.token }}
+        run: |-
+          gh repo clone ${{ github.repository }} ${{ github.workspace }} -- --branch "$BRANCH"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+      - name: Install tools
+        run: |
+          echo "/home/linuxbrew/.linuxbrew/bin" >> "$GITHUB_PATH"
+          /home/linuxbrew/.linuxbrew/bin/brew install \
+            go-task \
+            rye \
+      - name: Build package
+        run: task gendoc --yes
+      - name: Setup Pages
+        uses: actions/configure-pages@main
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@main
+        with:
+          path: './docs/build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@main

.gitignore

@@ -11,3 +11,5 @@ wheels/
 .python-version
 .sl/
 .task/
+docs/build/
+docs/source/apidocs/

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: latest
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py

Taskfile.yml

@@ -152,10 +152,20 @@ tasks:
         --skip-existing \
         --yes
 
+  gendoc:
+    desc: Generate documentation
+    deps: [sync]
+    sources:
+      - exclude: docs/source/apidocs/**
+      - docs/source/**
+    cmd: rye run sphinx-build -M html ./docs/source/ ./docs/build/
+
   clean:
     desc: Cleanup workspace
     cmds:
       - rm -rf ./dist/
       - rm -rf ./.ruff_cache/
       - rm -rf ./.pytest_cache/
       - fd --type directory --no-ignore __pycache__ | xargs --no-run-if-empty rm -rf
+      - rm -rf ./docs/build/*
+      - rm -rf ./docs/source/apidocs/*

docs/source/conf.py

@@ -0,0 +1,43 @@
+"""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
+
+project = "SOPSy"
+copyright = "2024, nikaro"
+author = "nikaro"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.githubpages",
+    "myst_parser",
+    "autodoc2",
+]
+autodoc2_packages = [
+    "../../src/sopsy",
+]
+autodoc2_render_plugin = "myst"
+
+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 = "furo"
+
+# -- Options for intersphinx extension ---------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}

docs/source/index.md

@@ -0,0 +1,6 @@
+# Welcome to SOPSy's documentation!
+
+```{toctree}
+usage
+apidocs/index
+```

docs/source/usage.md

@@ -0,0 +1,54 @@
+# Usage
+
+## Installation
+
+SOPS binary should be installed and available in your `$PATH`:
+
+```sh
+# use your package manager to install it
+brew install sops
+```
+
+Install the SOPSy library:
+
+```sh
+pip install sopsy
+
+# or with whatever your package/project manager is
+uv add sopsy
+```
+
+## Quickstart
+
+Retrieve a secret value:
+
+```python
+from sopsy import Sops
+
+sops = Sops("secrets.yml")
+
+my_secret_key = sops.get("my_secret_key")
+print(f"signle secret: {my_secret_key}")
+
+secrets = sops.decrypt()
+print(f"all my secrets: {secrets}")
+```
+
+Encrypt a file:
+
+```python
+import json
+from pathlib import Path
+from sopsy import Sops
+
+plaintext_content = json.dumps({"hello": "world"})
+Path("secrets.json").write_text(plaintext_content)
+
+s = Sops("secrets.json", in_place=True)
+# you either need a `.sops.yml` configuration file with `creation_rules` set
+# or append some arguments to the `Sops.global_args` attribute:
+# s.global_args.extend([
+#     "--age", "age1yt3tfqlfrwdwx0z0ynwplcr6qxcxfaqycuprpmy89nr83ltx74tqdpszlw"
+# ])
+s.encrypt()
+```

pyproject.toml

@@ -39,8 +39,12 @@ universal = true
 generate-hashes = true
 dev-dependencies = [
   "basedpyright>=1.15.1",
+  "furo>=2024.8.6",
+  "myst-parser>=3.0.1",
   "pytest>=7.4.3",
   "ruff>=0.6.3",
+  "sphinx>=7.1.2",
+  "sphinx-autodoc2>=0.5.0",
   "typing-extensions>=4.12.2",
 ]
 
@@ -58,6 +62,7 @@ force-single-line = true
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["ANN401", "INP001", "S101", "SLF001"]
+"docs/*" = ["A001", "INP001"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "pep257"