Restructure Documentation

.github/_typos.toml

@@ -1,5 +1,5 @@
 [files]
-extend-exclude = ["third_party/*", "*.svg"]
+extend-exclude = ["third_party/*", "*.svg", "Doxyfile.in"]
 
 [default.extend-words]
 dout = "dout"

.github/workflows/joss.yml

@@ -30,7 +30,7 @@ jobs:
         cd joss
         pandoc paper.md -o paper.pdf --bibliography ./paper.bib --pdf-engine=xelatex
         popd
-    - uses: actions/upload-artifact@v1.0.0
+    - uses: actions/upload-artifact@v4
       with:
         name: joss-paper
         path: build/doc/joss/paper.pdf 

.gitlab-ci.yml

@@ -639,47 +639,6 @@ sonarqube_cov:
     - bash <(curl -s https://codecov.io/bash) -f "\!*examples*" -f "\!*third_party*" -f "\!*c\\+\\+*" -f "\!*benchmark*"
 
 
-# Deploy documentation to github-pages
-gh-pages:
-  stage: deploy
-  interruptible: false
-  extends:
-    - .default_variables
-    - .deploy_condition
-    - .before_script_git_template
-    - .use_status-job-settings
-  variables:
-    PUBLIC_REPO: [email protected]:ginkgo-project/ginkgo-generated-documentation.git
-  script:
-    # build docs
-    - mkdir -p ${CI_JOB_NAME} && pushd ${CI_JOB_NAME}
-    - cmake ${CI_PROJECT_DIR}
-        -DCMAKE_CXX_COMPILER=${CXX_COMPILER}
-        -DCMAKE_CUDA_COMPILER=${CUDA_COMPILER} -DCMAKE_BUILD_TYPE=${BUILD_TYPE}
-        -DBUILD_SHARED_LIBS=ON ${EXTRA_CMAKE_FLAGS} -DGINKGO_DEVEL_TOOLS=OFF
-        -DGINKGO_BUILD_REFERENCE=OFF -DGINKGO_BUILD_OMP=OFF -DGINKGO_BUILD_CUDA=OFF
-        -DGINKGO_BUILD_HIP=OFF -DGINKGO_BUILD_SYCL=OFF -DGINKGO_BUILD_MPI=OFF
-        -DGINKGO_BUILD_TESTS=OFF -DGINKGO_BUILD_EXAMPLES=OFF
-        -DGINKGO_BUILD_DOC=ON -DGINKGO_DOC_GENERATE_PDF=ON
-    - make usr
-    - make pdf
-    - popd
-    # publish it
-    - git clone ${PUBLIC_REPO} -b gh-pages gh-pages-repo
-    - rm -rf gh-pages-repo/doc/${CI_COMMIT_REF_NAME}
-    - mkdir -p gh-pages-repo/doc
-    - mkdir -p gh-pages-repo/doc/pdf
-    - cp -r ${CI_JOB_NAME}/doc/usr gh-pages-repo/doc/${CI_COMMIT_REF_NAME}
-    - cp ${CI_JOB_NAME}/doc/pdf.pdf gh-pages-repo/doc/pdf/${CI_COMMIT_REF_NAME}.pdf
-    - export CURRENT_SHA="$(git rev-parse --short HEAD)"
-    - cd gh-pages-repo
-    - git add -A
-    - git diff --quiet HEAD ||
-      (git commit -m "Update documentation from ginkgo-project/ginkgo@${CURRENT_SHA}" && git push)
-  dependencies: null
-  needs: []
-
-
 threadsanitizer:
   stage: QoS_tools
   extends:

.readthedocs.yaml

@@ -0,0 +1,41 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  apt_packages:
+    - doxygen
+    - cmake
+    - graphviz
+  tools:
+    python: "3.11"
+  jobs:
+    pre_build:
+      - |
+        cmake -S . -B build \
+        -DGINKGO_BUILD_DOC=ON \
+        -DGINKGO_DOC_GENERATE_PDF=OFF \
+        -DGINKGO_BUILD_EXAMPLES=ON \
+        -DGINKGO_BUILD_TESTS=OFF \
+        -DGINKGO_BUILD_BENCHMARKS=OFF \
+        -DGINKGO_BUILD_REFERENCE=ON \
+        -DGINKGO_BUILD_OMP=OFF \
+        -DGINKGO_BUILD_CUDA=OFF \
+        -DGINKGO_BUILD_HIP=OFF \
+        -DGINKGO_BUILD_SYCL=OFF \
+        -DGINKGO_BUILD_MPI=OFF
+        cmake --build build -t doxygen -- -j
+        mkdir -p $READTHEDOCS_OUTPUT/html/
+        mv build/doc/html/_doxygen $READTHEDOCS_OUTPUT/html/_doxygen
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: doc/conf.py
+
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: doc/requirements.txt

BENCHMARKING.md

@@ -1,5 +1,4 @@
-Running the benchmarks                         {#benchmarking_ginkgo}
-----------------------
+# Running the benchmarks
 
 In addition to the unit tests designed to verify correctness, Ginkgo also
 includes an extensive benchmark suite for checking its performance on all Ginkgo

CITING.md

@@ -1,4 +1,4 @@
-# Citing Ginkgo                                           {#citing_ginkgo}
+# Citing Ginkgo
 
 The main Ginkgo paper describing Ginkgo's purpose, design and interface is
 available through the following reference:

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing guidelines                         {#contributing_guidelines}
+# Contributing guidelines
 
 We are glad that you are interested in contributing to Ginkgo. Please have a
 look at our coding guidelines before proposing a pull request.

INSTALL.md

@@ -1,5 +1,5 @@
-Installation Instructions                      {#install_ginkgo}
--------------------------------------
+# Installation Instructions
+
 ### Building
 
 Use the standard CMake build procedure:

TESTING.md

@@ -1,5 +1,5 @@
-Testing Instructions                            {#testing_ginkgo}
--------------------------------------
+# Testing Instructions
+
 ### Running the unit tests
 You need to compile ginkgo with `-DGINKGO_BUILD_TESTS=ON` option to be able to
 run the tests. 

doc/CMakeLists.txt

@@ -1,24 +1,16 @@
-cmake_minimum_required(VERSION 3.16)
-include(helpers.cmake)
-find_package(Doxygen REQUIRED)
-find_package(Perl REQUIRED)
-option(GINKGO_DOC_GENERATE_PDF "Generate PDF documentation" OFF)
-option(GINKGO_DOC_GENERATE_DEV "Generate internal documentation" OFF)
-option(GINKGO_DOC_GENERATE_EXAMPLES "Generate example documentation" ON)
-if(GINKGO_DOC_GENERATE_EXAMPLES)
-    add_subdirectory(examples)
-endif()
+add_subdirectory(_doxygen)
 
-set(default_predefined_macros "GKO_HAVE_PAPI_SDE=1 GINKGO_BUILD_MPI=1")
+find_program(sphinx-build
+    NAMES sphinx-build
+    REQUIRED
+)
 
-if (GINKGO_DOC_GENERATE_PDF)
-    find_package(LATEX COMPONENTS PDFLATEX REQUIRED)
-endif()
-
-ginkgo_doc_gen(usr Doxyfile-usr.in OFF USR_DOC.md)
-if (GINKGO_DOC_GENERATE_DEV)
-    ginkgo_doc_gen(dev Doxyfile-dev.in OFF DEV_DOC.md)
-endif()
-if (GINKGO_DOC_GENERATE_PDF)
-    ginkgo_doc_gen(pdf Doxyfile-pdf.in ON PDF_DOC.md)
-endif()
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/conf.py @ONLY)
+add_custom_target(sphinx-doc ALL
+    COMMAND
+    "${sphinx-build}" -M html ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}
+    --conf-dir ${CMAKE_CURRENT_BINARY_DIR}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Generating sphinx documentation"
+    VERBATIM
+)

doc/_doxygen/CMakeLists.txt

@@ -0,0 +1,25 @@
+cmake_minimum_required(VERSION 3.16)
+include(helpers.cmake)
+find_package(Doxygen REQUIRED)
+find_package(Perl REQUIRED)
+option(GINKGO_DOC_GENERATE_PDF "Generate PDF documentation" OFF)
+set(GINKGO_DOC_GENERATE_PDF_YESNO NO)
+if(GINKGO_DOC_GENERATE_PDF)
+    set(GINKGO_DOC_GENERATE_PDF_YESNO YES)
+endif()
+
+add_subdirectory(examples)
+
+if (GINKGO_DOC_GENERATE_PDF)
+    find_package(LATEX COMPONENTS PDFLATEX REQUIRED)
+endif()
+
+include(FetchContent)
+FetchContent_Declare(
+        doxygen_awesome
+        GIT_REPOSITORY https://github.com/jothepro/doxygen-awesome-css.git
+        GIT_TAG v2.3.3
+)
+FetchContent_MakeAvailable(doxygen_awesome)
+
+ginkgo_doc_gen()