Switch to Furo docs theme, check docs in CI (#12)

* Switch to Furo docs theme

* Check docs in CI

.github/workflows/tests.yml

@@ -22,3 +22,28 @@ jobs:
           pip-sync requirements/requirements.txt requirements/requirements-test.txt
       - name: Test with tox
         run: tox
+
+  docs:
+    name: Build and check documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: |
+          pip install pip-tools
+          pip-sync requirements/requirements.txt requirements/requirements-docs.txt
+      - name: Lint docs with sphinx-lint
+        run: |
+          sphinx-lint docs
+      - name: Build docs and check the integrity of external links
+        run: |
+          ls source
+          sphinx-build --builder linkcheck --fail-on-warning "source" "build"
+          sphinx-build --builder html --fail-on-warning "source" "build"
+        working-directory:
+          ./docs

docs/source/conf.py

@@ -52,8 +52,16 @@
     "python": ("https://docs.python.org/3", None),
 }
 
+linkcheck_retries = 3
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 html_static_path = ["_static"]
+
+html_theme_options = {
+    "source_repository": "https://github.com/Viicos/jsonlogic/",
+    "source_branch": "main",
+    "source_directory": "docs/source/",
+}

docs/source/usage/creating_operators.rst

@@ -114,4 +114,4 @@ operator.
 .. [#f1] You could implement some checks on the type of the provided argument,
    if it happens to be a :data:`~jsonlogic.typing.JSONLogicPrimitive` where the
    ``>`` argument doesn't make sense (arrays for instance). However, this is a
-   task better suited for typechecking.
+   task better suited for typechecking.

requirements/requirements-docs.in

@@ -1,4 +1,5 @@
 -c requirements.txt
+furo
 sphinx
-sphinx-rtd-theme
+sphinx-lint
 sphinx-paramlinks

requirements/requirements-docs.txt

@@ -8,15 +8,18 @@ alabaster==0.7.16
     # via sphinx
 babel==2.14.0
     # via sphinx
+beautifulsoup4==4.12.3
+    # via furo
 certifi==2024.2.2
     # via requests
 charset-normalizer==3.3.2
     # via requests
-docutils==0.20.1
+docutils==0.21.1
     # via
     #   sphinx
     #   sphinx-paramlinks
-    #   sphinx-rtd-theme
+furo==2024.1.29
+    # via -r requirements/requirements-docs.in
 idna==3.6
     # via requests
 imagesize==1.4.1
@@ -27,30 +30,38 @@ markupsafe==2.1.5
     # via jinja2
 packaging==24.0
     # via sphinx
+polib==1.2.0
+    # via sphinx-lint
 pygments==2.17.2
-    # via sphinx
+    # via
+    #   furo
+    #   sphinx
+regex==2024.4.16
+    # via sphinx-lint
 requests==2.31.0
     # via sphinx
 snowballstemmer==2.2.0
     # via sphinx
-sphinx==7.2.6
+soupsieve==2.5
+    # via beautifulsoup4
+sphinx==7.3.5
     # via
     #   -r requirements/requirements-docs.in
+    #   furo
+    #   sphinx-basic-ng
     #   sphinx-paramlinks
-    #   sphinx-rtd-theme
-    #   sphinxcontrib-jquery
-sphinx-paramlinks==0.6.0
+sphinx-basic-ng==1.0.0b2
+    # via furo
+sphinx-lint==0.9.1
     # via -r requirements/requirements-docs.in
-sphinx-rtd-theme==2.0.0
+sphinx-paramlinks==0.6.0
     # via -r requirements/requirements-docs.in
 sphinxcontrib-applehelp==1.0.8
     # via sphinx
 sphinxcontrib-devhelp==1.0.6
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.5
     # via sphinx
-sphinxcontrib-jquery==4.1
-    # via sphinx-rtd-theme
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
 sphinxcontrib-qthelp==1.0.7