Setup readthedocs and CI job for checking documentation building

.circleci/config.yml

@@ -10,7 +10,7 @@ executors:
     parameters:
       python_version:
         type: string
-        default: "3.10"
+        default: "3.11"
     docker:
       - image: cimg/python:<<parameters.python_version>>
 
@@ -53,6 +53,22 @@ jobs:
           name: Run pre-commit hooks
           command: pre-commit run --all-files
 
+  build-docs:
+    description: "Build docs check (the actual publishing is handled by .readthedocs.yaml)"
+    executor:
+      name: docker-executor
+    steps:
+      - checkout
+      - run:
+          name: Install poetry
+          command: python -m pip install poetry
+      - run:
+          name: Install build docs dependency
+          command: python -m poetry install --only=docs,dev
+      - run:
+          name: Run Sphinx
+          command: poetry run inv docs.build
+
 workflows:
   tests:
     jobs:
@@ -64,3 +80,5 @@ workflows:
           <<: *all_branches_and_version_tag
       - precommit:
           <<: *all_branches_and_version_tag
+      - build-docs:
+          <<: *all_branches_and_version_tag

.readthedocs.yaml

@@ -0,0 +1,18 @@
+---
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      - python -m pip install poetry
+      - python -m poetry config virtualenvs.create false
+    post_install:
+      # Install dependencies with 'docs' dependency group
+      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      - poetry install --only=docs,dev
+
+sphinx:
+  configuration: docs/conf.py

pyproject.toml

@@ -11,10 +11,10 @@ python = "^3.11"
 [tool.poetry.group.dev.dependencies]
 invoke = "^2.2.0"
 
-
 [tool.poetry.group.docs.dependencies]
 sphinx-book-theme = "^1.0.1"
 rich = "^13.6.0"
+myst-parser = "^2.0.0"
 
 [build-system]
 requires = ["poetry-core"]