From dceb640c7782024fec749dafb3876cdd2f50c996 Mon Sep 17 00:00:00 2001
From: Julian Stirling <julian@julianstirling.co.uk>
Date: Thu, 10 Jul 2025 00:06:39 +0100
Subject: [PATCH] Add documentation job to the CI.

---
 .gitlab-ci.yml | 32 ++++++++++++++++++++++++++++++++
 pyproject.toml |  1 +
 2 files changed, 33 insertions(+)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 77c2143b..c17e0f8d 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -168,6 +168,24 @@ build:
     paths:
       - "src/openflexure_microscope_server/static/"
 
+build-docs:
+  extends: .python
+  stage: build
+  script:
+    - pydoctor --docformat  restructuredtext --theme readthedocs src/openflexure_microscope_server
+    - echo "JOB_ID=$CI_JOB_ID" > build-docs.env
+  artifacts:
+    expire_in: 1 week
+    name: "${CI_PROJECT_NAME}-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}-${CI_COMMIT_SHORT_SHA}-docs"
+    paths:
+      - apidocs
+    reports:
+      dotenv: build-docs.env
+  environment:
+    name: review/$CI_COMMIT_REF_SLUG
+    url: https://$CI_PROJECT_ROOT_NAMESPACE.gitlab.io/-/openflexure-microscope-server/-/jobs/$JOB_ID/artifacts/apidocs/index.html
+
+
 server_integration_tests:
   extends: .python
   stage: integration
@@ -261,3 +279,17 @@ server_integration_tests:
 #   only:
 #     - tags
 #     - web
+
+pages:
+  needs:
+    - job: build-docs
+      artifacts: true
+  stage: deploy
+  image: "alpine:latest"
+  script:
+    - mv apidocs public
+  artifacts:
+      paths:
+      - public
+  only:
+    - v3
diff --git a/pyproject.toml b/pyproject.toml
index f0428cca..89a9156c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -40,6 +40,7 @@ dev = [
   "pytest-mock==3.14",
   "matplotlib~=3.10",
   "hypothesis",
+  "pydoctor"
 ]
 pi = [
   "picamera2~=0.3.27",