Merge pull request #30 from ilaflott/copilot/fix-sphinx-doc-builds-again

Add Sphinx doc build and RST linting CI workflow

Author: ilaflott

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: docs
+
+on:
+  pull_request:
+    branches:
+
+# cancel running jobs if theres a newer push
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+    steps:
+      - name: Checkout Files
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install doc dependencies
+        run: |
+          pip install sphinx renku-sphinx-theme sphinx-rtd-theme click pyyaml rstcheck
+
+      - name: Install fremorizer
+        run: |
+          pip install --no-deps .
+
+      - name: Lint RST files
+        run: |
+          rstcheck --recursive docs/
+
+      - name: Build Sphinx docs
+        run: |
+          sphinx-build -W --keep-going -b html docs docs/build/html

.gitignore

@@ -158,3 +158,4 @@ tmp/
 # autogen'd by doc build
 docs/fremorizer.*
 docs/modules.rst
+docs/build/

docs/api.rst

@@ -1,2 +1,5 @@
+API Reference
+=============
+
 .. automodule:: fremorizer
    :members:

docs/conf.py

@@ -9,7 +9,17 @@
 
 sys.path.insert(0, str(Path('..').resolve()))
 
-from fremorizer import __version__ as pkg_version
+import importlib.util
+
+# Load _version.py directly to avoid triggering the full package init
+# (which imports heavy optional dependencies like cmor, netCDF4, etc.)
+_ver_spec = importlib.util.spec_from_file_location(
+    "fremorizer._version",
+    Path('..').resolve() / 'fremorizer' / '_version.py'
+)
+_ver_mod = importlib.util.module_from_spec(_ver_spec)  # type: ignore[arg-type]
+_ver_spec.loader.exec_module(_ver_mod)  # type: ignore[union-attr]
+pkg_version = _ver_mod.__version__
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx
 renku-sphinx-theme
 sphinx-rtd-theme
+rstcheck

pyproject.toml

@@ -53,9 +53,15 @@ docs = [
     "sphinx",
     "renku-sphinx-theme",
     "sphinx-rtd-theme",
+    "rstcheck",
 ]
 
 test = [
     "pylint",
     "pytest",
 ]
+
+
+[tool.rstcheck]
+report_level = "WARNING"
+ignore_directives = ["automodule", "autoclass", "autofunction", "automethod", "autoattribute"]