Update documentation build to use "assets" (#316)

* Rename workflow. * Combine documentation and update workflow. * Trying to provide multipleriggers. * Correct trigger name. * WiP * Syntax error. * Check out source before referencing it. * Manual dispatch still needed. * Enhanced permissions. * Correct permission label. * Molify style checker.
MetOffice · Jun 28, 2024 · 3452576 · 3452576
1 parent 529522b
commit 3452576
Show file tree

Hide file tree

Showing 27 changed files with 93 additions and 104 deletions.
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,56 @@
+name: Build Documentation
+
+on:
+  push:
+    branches:
+      - 'main'
+  workflow_dispatch:
+
+jobs:
+  sphinx-build:
+
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: Cache Python packages
+      uses: actions/cache@v4
+      with:
+        path: ~/.pip/cache
+        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/pyproject.toml') }}
+
+    - name: Install Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Check out Fab source
+      uses: actions/checkout@v4
+
+    - name: Install documentation tools
+      run: pip install .[docs]
+
+    - name: Generate documentation
+      run: |
+        cd Documentation
+        sphinx-apidoc --separate --module-first -d 5 -f -o source/apidoc ../source/fab
+        make html
+
+    - name: Prepare and upload asset
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: Documentation/build/html
+
+
+  deploy-documentation:
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{steps.deploy-documentation.outputs.page_url}}
+    runs-on: ubuntu-24.04
+    needs: sphinx-build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/Makefile → Documentation/Makefile b/docs/Makefile → Documentation/Makefile
diff --git a/docs/make.bat → Documentation/make.bat b/docs/make.bat → Documentation/make.bat
@@ -1,35 +1,35 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/_templates/crown-copyright.html → ...on/source/_templates/crown-copyright.html b/docs/source/_templates/crown-copyright.html → ...on/source/_templates/crown-copyright.html
diff --git a/docs/source/advanced_config.rst → Documentation/source/advanced_config.rst b/docs/source/advanced_config.rst → Documentation/source/advanced_config.rst
diff --git a/docs/source/api.rst → Documentation/source/api.rst b/docs/source/api.rst → Documentation/source/api.rst
diff --git a/docs/source/conf.py → Documentation/source/conf.py b/docs/source/conf.py → Documentation/source/conf.py
@@ -12,6 +12,7 @@
 #
 import os
 import sys
+from fab import __version__ as fab_version
 sys.path.insert(0, os.path.abspath('../../source'))
 
 
@@ -22,8 +23,7 @@
 author = 'Fab Team'
 
 # The full version, including alpha/beta/rc tags
-import fab
-release = fab.__version__
+release = fab_version
 
 # The version up to the minor patch, for distinguishing multi-version docs
 version = '.'.join(release.split('.')[:2])

diff --git a/docs/source/config_intro.rst → Documentation/source/config_intro.rst b/docs/source/config_intro.rst → Documentation/source/config_intro.rst
diff --git a/docs/source/development.rst → Documentation/source/development.rst b/docs/source/development.rst → Documentation/source/development.rst
diff --git a/docs/source/environment.rst → Documentation/source/environment.rst b/docs/source/environment.rst → Documentation/source/environment.rst
diff --git a/docs/source/features.rst → Documentation/source/features.rst b/docs/source/features.rst → Documentation/source/features.rst
diff --git a/docs/source/genindex.rst → Documentation/source/genindex.rst b/docs/source/genindex.rst → Documentation/source/genindex.rst
diff --git a/docs/source/glossary.rst → Documentation/source/glossary.rst b/docs/source/glossary.rst → Documentation/source/glossary.rst
diff --git a/...source/img/analysis_results_hierarchy.svg → ...source/img/analysis_results_hierarchy.svg b/...source/img/analysis_results_hierarchy.svg → ...source/img/analysis_results_hierarchy.svg
diff --git a/docs/source/img/busby.png → Documentation/source/img/busby.png b/docs/source/img/busby.png → Documentation/source/img/busby.png
diff --git a/docs/source/img/hist.png → Documentation/source/img/hist.png b/docs/source/img/hist.png → Documentation/source/img/hist.png
diff --git a/docs/source/img/pie.png → Documentation/source/img/pie.png b/docs/source/img/pie.png → Documentation/source/img/pie.png
diff --git a/docs/source/img/steps_and_artefacts.svg → ...tation/source/img/steps_and_artefacts.svg b/docs/source/img/steps_and_artefacts.svg → ...tation/source/img/steps_and_artefacts.svg
diff --git a/docs/source/index.rst → Documentation/source/index.rst b/docs/source/index.rst → Documentation/source/index.rst
diff --git a/docs/source/install.rst → Documentation/source/install.rst b/docs/source/install.rst → Documentation/source/install.rst
diff --git a/docs/source/metoffice.rst → Documentation/source/metoffice.rst b/docs/source/metoffice.rst → Documentation/source/metoffice.rst
diff --git a/docs/source/py-modindex.rst → Documentation/source/py-modindex.rst b/docs/source/py-modindex.rst → Documentation/source/py-modindex.rst
diff --git a/docs/source/site-specific-config.rst → ...mentation/source/site-specific-config.rst b/docs/source/site-specific-config.rst → ...mentation/source/site-specific-config.rst
diff --git a/docs/source/writing_config.rst → Documentation/source/writing_config.rst b/docs/source/writing_config.rst → Documentation/source/writing_config.rst
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/readme b/docs/readme