From 345257606fe344ec14965766fcd7329552559ffb Mon Sep 17 00:00:00 2001 From: Matthew Hambley Date: Fri, 28 Jun 2024 06:11:33 +0100 Subject: [PATCH] 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. --- .github/workflows/build_docs.yml | 52 ------------- .github/workflows/documentation.yml | 56 ++++++++++++++ {docs => Documentation}/Makefile | 0 {docs => Documentation}/make.bat | 70 +++++++++--------- .../source/_templates/crown-copyright.html | 0 .../source/advanced_config.rst | 0 {docs => Documentation}/source/api.rst | 0 {docs => Documentation}/source/conf.py | 4 +- .../source/config_intro.rst | 0 .../source/development.rst | 0 .../source/environment.rst | 0 {docs => Documentation}/source/features.rst | 0 {docs => Documentation}/source/genindex.rst | 0 {docs => Documentation}/source/glossary.rst | 0 .../source/img/analysis_results_hierarchy.svg | 0 {docs => Documentation}/source/img/busby.png | Bin {docs => Documentation}/source/img/hist.png | Bin {docs => Documentation}/source/img/pie.png | Bin .../source/img/steps_and_artefacts.svg | 0 {docs => Documentation}/source/index.rst | 0 {docs => Documentation}/source/install.rst | 0 {docs => Documentation}/source/metoffice.rst | 0 .../source/py-modindex.rst | 0 .../source/site-specific-config.rst | 0 .../source/writing_config.rst | 0 docs/.nojekyll | 0 docs/readme | 15 ---- 27 files changed, 93 insertions(+), 104 deletions(-) delete mode 100644 .github/workflows/build_docs.yml create mode 100644 .github/workflows/documentation.yml rename {docs => Documentation}/Makefile (100%) rename {docs => Documentation}/make.bat (95%) rename {docs => Documentation}/source/_templates/crown-copyright.html (100%) rename {docs => Documentation}/source/advanced_config.rst (100%) rename {docs => Documentation}/source/api.rst (100%) rename {docs => Documentation}/source/conf.py (98%) rename {docs => Documentation}/source/config_intro.rst (100%) rename {docs => Documentation}/source/development.rst (100%) rename {docs => Documentation}/source/environment.rst (100%) rename {docs => Documentation}/source/features.rst (100%) rename {docs => Documentation}/source/genindex.rst (100%) rename {docs => Documentation}/source/glossary.rst (100%) rename {docs => Documentation}/source/img/analysis_results_hierarchy.svg (100%) rename {docs => Documentation}/source/img/busby.png (100%) rename {docs => Documentation}/source/img/hist.png (100%) rename {docs => Documentation}/source/img/pie.png (100%) rename {docs => Documentation}/source/img/steps_and_artefacts.svg (100%) rename {docs => Documentation}/source/index.rst (100%) rename {docs => Documentation}/source/install.rst (100%) rename {docs => Documentation}/source/metoffice.rst (100%) rename {docs => Documentation}/source/py-modindex.rst (100%) rename {docs => Documentation}/source/site-specific-config.rst (100%) rename {docs => Documentation}/source/writing_config.rst (100%) delete mode 100644 docs/.nojekyll delete mode 100644 docs/readme diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml deleted file mode 100644 index 8716de74..00000000 --- a/.github/workflows/build_docs.yml +++ /dev/null @@ -1,52 +0,0 @@ -name: Build Docs - -on: workflow_dispatch - -jobs: - build-docs: - - runs-on: ubuntu-22.04 - - steps: - - name: set git user - run: | - git config --global user.email "CoreCapabilityDevelopmentTeam@metoffice.gov.uk" - git config --global user.name "SciFab Developers" - - - name: Checkout Fab project files - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 - with: - python-version: '3.x' - cache: pip - - - name: Install Python libraries - run: | - python -m pip install --upgrade pip - pip install -e .[docs] - - - name: build docs - run: | - cd docs - rm -rf build - sphinx-apidoc --separate --module-first -d 5 -f -o source/apidoc ../source/fab - make html - - - name: move built docs to docs root - run: | - mv docs/build/html/* docs/ - - - name: git add built docs - run: | - git add docs/* - - - name: commit - run: | - git commit -m "docs build" - - - name: push to gh_pages branch - run: | - echo "pushing from $GITHUB_REF_NAME to gh_pages" - git push --force origin $GITHUB_REF_NAME:gh_pages diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..e64637f5 --- /dev/null +++ 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 b/Documentation/Makefile similarity index 100% rename from docs/Makefile rename to Documentation/Makefile diff --git a/docs/make.bat b/Documentation/make.bat similarity index 95% rename from docs/make.bat rename to Documentation/make.bat index 6fcf05b4..061f32f9 100644 --- a/docs/make.bat +++ b/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 b/Documentation/source/_templates/crown-copyright.html similarity index 100% rename from docs/source/_templates/crown-copyright.html rename to Documentation/source/_templates/crown-copyright.html diff --git a/docs/source/advanced_config.rst b/Documentation/source/advanced_config.rst similarity index 100% rename from docs/source/advanced_config.rst rename to Documentation/source/advanced_config.rst diff --git a/docs/source/api.rst b/Documentation/source/api.rst similarity index 100% rename from docs/source/api.rst rename to Documentation/source/api.rst diff --git a/docs/source/conf.py b/Documentation/source/conf.py similarity index 98% rename from docs/source/conf.py rename to Documentation/source/conf.py index d036262f..cb6a185b 100644 --- a/docs/source/conf.py +++ b/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 b/Documentation/source/config_intro.rst similarity index 100% rename from docs/source/config_intro.rst rename to Documentation/source/config_intro.rst diff --git a/docs/source/development.rst b/Documentation/source/development.rst similarity index 100% rename from docs/source/development.rst rename to Documentation/source/development.rst diff --git a/docs/source/environment.rst b/Documentation/source/environment.rst similarity index 100% rename from docs/source/environment.rst rename to Documentation/source/environment.rst diff --git a/docs/source/features.rst b/Documentation/source/features.rst similarity index 100% rename from docs/source/features.rst rename to Documentation/source/features.rst diff --git a/docs/source/genindex.rst b/Documentation/source/genindex.rst similarity index 100% rename from docs/source/genindex.rst rename to Documentation/source/genindex.rst diff --git a/docs/source/glossary.rst b/Documentation/source/glossary.rst similarity index 100% rename from docs/source/glossary.rst rename to Documentation/source/glossary.rst diff --git a/docs/source/img/analysis_results_hierarchy.svg b/Documentation/source/img/analysis_results_hierarchy.svg similarity index 100% rename from docs/source/img/analysis_results_hierarchy.svg rename to Documentation/source/img/analysis_results_hierarchy.svg diff --git a/docs/source/img/busby.png b/Documentation/source/img/busby.png similarity index 100% rename from docs/source/img/busby.png rename to Documentation/source/img/busby.png diff --git a/docs/source/img/hist.png b/Documentation/source/img/hist.png similarity index 100% rename from docs/source/img/hist.png rename to Documentation/source/img/hist.png diff --git a/docs/source/img/pie.png b/Documentation/source/img/pie.png similarity index 100% rename from docs/source/img/pie.png rename to Documentation/source/img/pie.png diff --git a/docs/source/img/steps_and_artefacts.svg b/Documentation/source/img/steps_and_artefacts.svg similarity index 100% rename from docs/source/img/steps_and_artefacts.svg rename to Documentation/source/img/steps_and_artefacts.svg diff --git a/docs/source/index.rst b/Documentation/source/index.rst similarity index 100% rename from docs/source/index.rst rename to Documentation/source/index.rst diff --git a/docs/source/install.rst b/Documentation/source/install.rst similarity index 100% rename from docs/source/install.rst rename to Documentation/source/install.rst diff --git a/docs/source/metoffice.rst b/Documentation/source/metoffice.rst similarity index 100% rename from docs/source/metoffice.rst rename to Documentation/source/metoffice.rst diff --git a/docs/source/py-modindex.rst b/Documentation/source/py-modindex.rst similarity index 100% rename from docs/source/py-modindex.rst rename to Documentation/source/py-modindex.rst diff --git a/docs/source/site-specific-config.rst b/Documentation/source/site-specific-config.rst similarity index 100% rename from docs/source/site-specific-config.rst rename to Documentation/source/site-specific-config.rst diff --git a/docs/source/writing_config.rst b/Documentation/source/writing_config.rst similarity index 100% rename from docs/source/writing_config.rst rename to Documentation/source/writing_config.rst diff --git a/docs/.nojekyll b/docs/.nojekyll deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/readme b/docs/readme deleted file mode 100644 index 8ad71401..00000000 --- a/docs/readme +++ /dev/null @@ -1,15 +0,0 @@ - - -# these commands build the docs -rm -rf build -rm -rf source/apidoc -sphinx-apidoc --separate --module-first -d 5 -f -o source/apidoc ../source/fab -make html - - -# all in one -rm -rf build && rm -rf source/apidoc && sphinx-apidoc --separate --module-first -d 5 -f -o source/apidoc ../source/fab && make html -firefox build/html/index.html - - -# the -d 5 controls the toc depth on the main api reference page, letting us see the individual step modules \ No newline at end of file