Move docs to gh-pages (#1307)

.github/problem-matchers/gcc.json

@@ -0,0 +1,18 @@
+{
+     "__comment": "Taken from vscode-cpptools's Extension/package.json gcc rule",
+     "problemMatcher": [
+         {
+             "owner": "gcc-problem-matcher",
+             "pattern": [
+                 {
+                     "regexp": "^(.*):(\\d+):(\\d+):\\s+(?:fatal\\s+)?(warning|error):\\s+(.*)$",
+                     "file": 1,
+                     "line": 2,
+                     "column": 3,
+                     "severity": 4,
+                     "message": 5
+                 }
+             ]
+         }
+     ]
+} 

.github/problem-matchers/sphinx.json

@@ -0,0 +1,40 @@
+{
+     "problemMatcher": [
+         {
+             "owner": "sphinx-problem-matcher",
+             "pattern": [
+                 {
+                     "regexp": "^(.*):(\\d+):\\s+(\\w*):\\s+(.*)$",
+                     "file": 1,
+                     "line": 2,
+                     "severity": 3,
+                     "message": 4
+                 }
+             ]
+         },
+         {
+             "owner": "sphinx-problem-matcher-loose",
+             "pattern": [
+                 {
+                     "_comment": "A bit of a looser pattern, doesn't look for line numbers, just looks for file names relying on them to start with / and end with .rst",
+                     "regexp": "(\/.*\\.rst):\\s+(\\w*):\\s+(.*)$",
+                     "file": 1,
+                     "severity": 2,
+                     "message": 3
+                 }
+             ]
+         },
+         {
+             "owner": "sphinx-problem-matcher-loose-no-severity",
+             "pattern": [
+                 {
+                     "_comment": "Looks for file names ending with .rst and line numbers but without severity",
+                     "regexp": "^(.*\\.rst):(\\d+):(.*)$",
+                     "file": 1,
+                     "line": 2,
+                     "message": 3
+                 }
+             ]           
+         }
+     ]
+} 

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Nalu-Wind-Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{github.ref}}-${{github.head_ref}}-docs
+  cancel-in-progress: true
+
+jobs:
+  Docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone
+        uses: actions/checkout@v4
+      - name: Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      - name: Dependencies
+        run: |
+          export DEBIAN_FRONTEND=noninteractive
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends doxygen graphviz
+          python3 -m pip install --upgrade pip
+          pip3 install sphinx sphinx_rtd_theme
+      - name: Build
+        # execute from top-level nalu-wind directory
+        run: |
+          echo "::add-matcher::.github/problem-matchers/sphinx.json"
+          sphinx-build -M html ./docs/sphinx ./build_docs/manual -W --keep-going -n 2>&1 | tee -a build-output.txt
+          # Doxygen output gets parsed wrong by the sphinx problem matcher so unregister it
+          echo "::remove-matcher owner=sphinx-problem-matcher-loose-no-severity::"
+          echo "::remove-matcher owner=sphinx-problem-matcher-loose::"
+          echo "::remove-matcher owner=sphinx-problem-matcher::"
+          doxygen ./docs/doxygen/Doxyfile
+          mv ./build_docs/manual/html ./documentation
+          mv ./build_docs/doxygen/html ./documentation/api_docs
+          touch ./documentation/.nojekyll
+      - name: Report
+        run: |
+          echo "::add-matcher::.github/problem-matchers/sphinx.json"
+          egrep "WARNING:" build-output.txt | sort | uniq | \
+            awk 'BEGIN{i=0}{print $0}{i++}END{print "Warnings: "i}' > build-output-warnings.txt
+          cat build-output-warnings.txt
+          exit $(tail -n 1 build-output-warnings.txt | awk '{print $2}')
+      - name: Deploy
+        if: github.event_name == 'push'
+        uses: JamesIves/github-pages-deploy-action@releases/v3
+        with:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          BRANCH: gh-pages
+          FOLDER: documentation
+          SINGLE_COMMIT: true

CMakeLists.txt

@@ -10,8 +10,6 @@ option(ENABLE_ROCM "Enable build targeting AMD GPU" OFF)
 option(ENABLE_UMPIRE "Enable Umpire GPU memory pools" OFF)
 option(ENABLE_TESTS "Enable regression testing." OFF)
 option(ENABLE_UNIT_TESTS "Enable unit testing." ON)
-option(ENABLE_DOCUMENTATION "Build documentation." OFF)
-option(ENABLE_SPHINX_API_DOCS "Link Doxygen API docs to Sphinx" OFF)
 option(ENABLE_WIND_UTILS "Build wind utils along with Nalu-Wind" OFF)
 option(ENABLE_FFTW "Use the FFTW library to support ABLTopBC" OFF)
 option(ENABLE_HYPRE "Use HYPRE Solver library" ON)
@@ -313,10 +311,6 @@ endif()
 include(CMakePackageConfigHelpers)
 include(GNUInstallDirs)
 
-if(ENABLE_DOCUMENTATION)
-   add_subdirectory(docs)
-endif()
-
 if(ENABLE_TESTS)
    enable_testing()
    include(CTest)