Merge topic 'add-sphinx-ci'

181d5616e build,docs: add sphinx to CI
7f400505c build,docs: add sphinx to CI

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Vicente Bolea <vicente.bolea@kitware.com>
Merge-request: !3142

.gitlab-ci.yml

@@ -55,7 +55,7 @@
     - .docker_image
 
 .ubuntu2004_doxygen: &ubuntu2004_doxygen
-  image: "kitware/vtkm:ci-doxygen-20230906"
+  image: "kitware/vtkm:ci-doxygen-20231020"
   extends:
     - .docker_image
 

.gitlab/ci/docker/ubuntu2004/doxygen/Dockerfile

@@ -26,9 +26,17 @@ RUN apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-ins
       libtbb-dev \
       mpich \
       ninja-build \
+      python3-pip \
       rsync \
-      ssh \
-      software-properties-common
+      software-properties-common \
+      ssh
+
+RUN python3 -m pip install \
+      breathe \
+      sphinx \
+      sphinxcontrib-moderncmakedomain \
+      sphinxcontrib-packages \
+      sphinx-rtd-theme
 
 # Need to run git-lfs install manually on ubuntu based images when using the
 # system packaged version

.gitlab/ci/doxygen.yml

@@ -10,7 +10,12 @@
 ##
 ##=============================================================================
 
-.doxygen_submit: &doxygen_submit
+.upload_doxygen: &upload_doxygen
+  script:
+    - chmod 400 $DOC_KEY_FILE
+    - rsync -rtv --delete -e "ssh -i $DOC_KEY_FILE -o StrictHostKeyChecking=no" build/docs/doxygen/html/ "kitware@web.kitware.com:vtkm_documentation/$DOXYGEN_UPLOAD_REMOTE_PATH"
+
+.build_docs: &build_docs
   stage: build
   tags:
     - build
@@ -18,19 +23,26 @@
     - docker
     - linux-x86_64
   before_script:
-    - "cmake -V -P .gitlab/ci/config/gitlab_ci_setup.cmake"
-    - "ctest -VV -S .gitlab/ci/ctest_configure.cmake"
-  script:
-    - doxygen build/docs/doxyfile
-    - chmod 400 $DOC_KEY_FILE
-    - rsync -tv --recursive --delete -e "ssh -i $DOC_KEY_FILE -o StrictHostKeyChecking=no" build/docs/doxygen/html/ "kitware@web.kitware.com:vtkm_documentation/$DOXYGEN_UPLOAD_REMOTE_PATH"
+    - cmake -V -P .gitlab/ci/config/gitlab_ci_setup.cmake
+    - ctest -VV -S .gitlab/ci/ctest_configure.cmake
+    - cmake --build "${CI_PROJECT_DIR}/build" --target VTKmUsersGuideLaTeX
+    - cmake --build "${CI_PROJECT_DIR}/build" --target VTKmUsersGuideHTML
+    - cmake --build "${CI_PROJECT_DIR}/build" --target docs/doxygen
   timeout:  30 minutes
   interruptible: true
   variables:
     CMAKE_BUILD_TYPE: Release
     VTKM_SETTINGS: "tbb+openmp+mpi+shared+docs"
 
-docs:nightly:
+docs:continous:
+  script:
+    - "true"
+  extends:
+    - .run_automatically
+    - .ubuntu2004_doxygen
+    - .build_docs
+
+docs:master:
   environment:
     name: doxygen-nightly
     url: https://docs-m.vtk.org/nightly/
@@ -40,7 +52,8 @@ docs:nightly:
     - when: never
   extends:
     - .ubuntu2004_doxygen
-    - .doxygen_submit
+    - .build_docs
+    - .upload_doxygen
   variables:
     DOXYGEN_UPLOAD_REMOTE_PATH: "nightly"
 
@@ -54,6 +67,7 @@ docs:latest:
     - when: never
   extends:
     - .ubuntu2004_doxygen
-    - .doxygen_submit
+    - .build_docs
+    - .upload_doxygen
   variables:
     DOXYGEN_UPLOAD_REMOTE_PATH: "latest"

.readthedocs.yaml

@@ -1,6 +1,14 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+##=============================================================================
+##
+##  Copyright (c) Kitware, Inc.
+##  All rights reserved.
+##  See LICENSE.txt for details.
+##
+##  This software is distributed WITHOUT ANY WARRANTY; without even
+##  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+##  PURPOSE.  See the above copyright notice for more information.
+##
+##=============================================================================
 
 # Required
 version: 2
@@ -10,19 +18,13 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
-    # You can also specify other tool versions:
-    # nodejs: "19"
-    # rust: "1.64"
-    # golang: "1.19"
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+   configuration: docs/users-guide/conf.py
 
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#    - pdf
-#    - epub
+formats:
+   - pdf
+   - epub
 
 # Optional but recommended, declare the Python requirements required
 # to build your documentation