Setup Read-the-Docs (#314)

- Add `docs/api_reference/Taskfile.yml`
  - This is included as `api_reference` to top Taskfile.
- Introduce `docs/api_reference/pyproject.toml` and `uv` for building
sphinx document
  - For yielding `requirements.txt` via `uv pip compile`
- Drop `sphinx` and plugins from `[dev]` of `ommx` and
`ommx-python-mip-adapter`

.github/workflows/doc.yml

@@ -98,11 +98,8 @@ jobs:
       - name: Setup Environment
         uses: ./.github/actions/setup-test-environment
 
-      - name: Install dependencies
-        run: task install
-
       - name: Build Python documentation
-        run: task doc_python
+        run: task api_reference:build
 
       - name: Upload HTML
         uses: actions/upload-artifact@v4

.readthedocs.yaml

@@ -0,0 +1,31 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "23"
+    # rust: "1.82"
+    # golang: "1.23"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/api_reference/conf.py
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/api_reference/requirements.txt

Taskfile.yml

@@ -2,6 +2,11 @@
 # yaml-language-server: $schema=https://taskfile.dev/schema.json
 version: "3"
 
+includes:
+  api_reference:
+    taskfile: docs/api_reference/Taskfile.yml
+    dir: docs/api_reference
+
 tasks:
   # Documents
   build_book_ja:
@@ -143,15 +148,6 @@ tasks:
       - pytest -vv --doctest-modules python/ommx-openjij-adapter/
       - pyright python/ommx-openjij-adapter/
 
-  doc_python:
-    cmds:
-      - sphinx-build -b html . _build/html
-    dir: docs/api_reference
-
-  open_doc_python:
-    cmds:
-      - python -m webbrowser file:///$(pwd)/docs/api_reference/_build/html/autoapi/index.html
-
   stubgen:
     cmds:
       - cargo run --bin stub_gen --features=stub_gen

docs/api_reference/Taskfile.yml

@@ -0,0 +1,19 @@
+# https://taskfile.dev
+# yaml-language-server: $schema=https://taskfile.dev/schema.json
+version: "3"
+
+tasks:
+  build:
+    desc: "Build the API Reference of OMMX Python SDK"
+    cmds:
+      - uv run sphinx-build -b html . _build/html
+
+  open:
+    desc: "Open the API Reference on the browser"
+    cmds:
+      - uv run python -m webbrowser file:///$(pwd)/_build/html/autoapi/index.html
+
+  pip_compile:
+    desc: "Compile requirements.txt for depolyment to readthedocs"
+    cmds:
+      - uv pip compile pyproject.toml -o requirements.txt

docs/api_reference/conf.py

@@ -31,6 +31,7 @@
     "sphinx_rtd_theme",
     "sphinx_fontawesome",
     "autoapi.extension",
+    "myst_parser",
 ]
 source_suffix = {
     ".rst": "restructuredtext",

docs/api_reference/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "ommx-api-reference"
+version = "0.1.0"
+description = "Add your description here"
+requires-python = ">=3.9, <3.13"
+dependencies = [
+    "myst-parser>=3.0.1",
+    "sphinx-autoapi>=3.5.0",
+    "sphinx-fontawesome>=0.0.6",
+    "sphinx-rtd-theme>=3.0.2",
+    "sphinx>=7.4.7",
+    "tomlkit>=0.13.2",
+]