Revise documentation deployment (#365)

Uses built-in Jekyll to publish to Github pages. Refines FORD processing.
earth-system-radiation · Feb 26, 2025 · 63b5468 · 63b5468
1 parent e74fdbc
commit 63b5468
Show file tree

Hide file tree

Showing 26 changed files with 39 additions and 69 deletions.
diff --git a/.github/workflows/doc-deployment.yml b/.github/workflows/doc-deployment.yml
@@ -8,83 +8,47 @@ on:
 
 jobs:
   Build:
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     steps:
     #
     # Checks-out repository under $GITHUB_WORKSPACE
     #
     - uses: actions/checkout@v4
     #
-    # Synchronize the package index
-    #
-    - name: Synchronize the package index
-      run: sudo apt-get update
-    #
     # Install dependencies
     #
     - name: Install dependencies
       run: |
+        sudo apt-get update
         sudo apt-get install graphviz
         sudo pip install 'markdown<3.4' ford
     #
-    # Install Ruby
-    #
-    - name: Install Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: 3.1
-    #
-    # Install Jekyll
-    #
-    - name: Install Jekyll
-      run: |
-        cd doc/jekyll_site
-        sudo gem install bundler jekyll
-        bundle update
-    #
     # Build documentation
     #
-    - name: Build Documentation
+    - name: Build FORD files
+      id: build
       run: |
-        cd doc
-        ./build_documentation.sh -ci
-    #
-    # Upload documentation
-    #
-    - name: Upload Documentation
-      uses: actions/upload-artifact@v4
-      with:
-        name: documentation
-        path: public/
-        if-no-files-found: error
-    #
-    # Check broken links
-    #
-    - name: Broken Link Check
-      if: ${{ github.ref == 'refs/heads/main'}}
-      uses: technote-space/broken-link-checker-action@v2
-      with:
-        TARGET: file://${{ github.workspace }}/doc/ford_site/pages/index.html
-        RECURSIVE: true
-        ASSIGNEES: ${{ github.actor }}
+        cd docs
+        ford ford_templates/rrtmgp-fortran-interface.md
+        ford ford_templates/rrtmgp-kernels.md
+        ford ford_templates/rte-fortran-interface.md
+        ford ford_templates/rte-kernels.md
     #
     # Deploy
     #
-    - name: Deploy to Github Pages root
+    - name: Deploy to Github Pages
       uses: JamesIves/[email protected]
       if: ${{ github.event_name == 'push'  &&  github.ref == 'refs/heads/main' }}
       with:
         branch: gh-pages
-        folder: public/
+        folder: docs/
 
-    #
-    # Deploy documentation (can add target-folder)
-    #   Won't run on pull requests or push unless a new branch is added to the on: section
-    #
-    - name: Deploy to Github Pages folder
+   #
+   # Deploy from workflow dispatch
+   #
+    - name: Deploy to Github Pages from workflow_dispatch
       uses: JamesIves/[email protected]
-      if: ${{ github.event_name == 'push'  &&  github.ref != 'refs/heads/main' }}
+      if: ${{ github.event_name == 'workflow_dispatch' }}
       with:
         branch: gh-pages
-        folder: public/
-        target-folder: staging/
+        folder: docs/
diff --git a/doc/jekyll_site/.gitignore → docs/.gitignore b/doc/jekyll_site/.gitignore → docs/.gitignore
@@ -5,3 +5,4 @@ _site
 .bundle
 vendor
 Gemfile.lock
+**/.DS_Store
diff --git a/doc/jekyll_site/Gemfile → docs/Gemfile b/doc/jekyll_site/Gemfile → docs/Gemfile
@@ -7,12 +7,12 @@ source "https://rubygems.org"
 #
 # This will help ensure the proper Jekyll version is running.
 # Happy Jekylling!
-gem "jekyll", "~> 4.2.1"
+#gem "jekyll", "~> 4.2.1"
 # This is the default theme for new Jekyll sites. You may change this to anything you like.
 gem "minima", "~> 2.5.1"
 # If you want to use GitHub Pages, remove the "gem "jekyll"" above and
 # uncomment the line below. To upgrade, run `bundle update github-pages`.
-# gem "github-pages", group: :jekyll_plugins
+gem "github-pages",  "~> 232", group: :jekyll_plugins
 # If you have any plugins, put them here!
 group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.12"

diff --git a/doc/jekyll_site/_config.yml → docs/_config.yml b/doc/jekyll_site/_config.yml → docs/_config.yml
@@ -43,6 +43,9 @@ header_pages:
 # remote_theme: rundocs/jekyll-rtd-theme
 #   from https://github.com/jekyllrtdtheme/jekyll-rtd-theme/
 #   May require new _config.yml? Example at https://github.com/darren1998s/darren1998s.github.io ?
+
+mathjax: true
+
 # plugins:
 #   - jekyll-feed
 
@@ -54,6 +57,8 @@ header_pages:
 # Excluded items can be processed by explicitly listing the directories or
 # their entries' file path in the `include:` list.
 #
+exclude:
+    - ford_templates/
 # exclude:
 #   - .sass-cache/
 #   - .jekyll-cache/

diff --git a/doc/build_documentation.sh → docs/build_documentation.sh b/doc/build_documentation.sh → docs/build_documentation.sh
diff --git a/doc/class_diagrams/mo_optical_props.puml → docs/class_diagrams/mo_optical_props.puml b/doc/class_diagrams/mo_optical_props.puml → docs/class_diagrams/mo_optical_props.puml
diff --git a/doc/jekyll_site/explanations/index.md → docs/explanations/index.md b/doc/jekyll_site/explanations/index.md → docs/explanations/index.md
diff --git a/doc/jekyll_site/explanations/rte-fluxes.md → docs/explanations/rte-fluxes.md b/doc/jekyll_site/explanations/rte-fluxes.md → docs/explanations/rte-fluxes.md
diff --git a/...ll_site/explanations/rte-optical-props.md → docs/explanations/rte-optical-props.md b/...ll_site/explanations/rte-optical-props.md → docs/explanations/rte-optical-props.md
diff --git a/doc/jekyll_site/explanations/rte-optics.md → docs/explanations/rte-optics.md b/doc/jekyll_site/explanations/rte-optics.md → docs/explanations/rte-optics.md
diff --git a/doc/jekyll_site/explanations/rte-solvers.md → docs/explanations/rte-solvers.md b/doc/jekyll_site/explanations/rte-solvers.md → docs/explanations/rte-solvers.md
diff --git a/doc/ford_site/rrtmgp-fortran-interface.md → ...ord_templates/rrtmgp-fortran-interface.md b/doc/ford_site/rrtmgp-fortran-interface.md → ...ord_templates/rrtmgp-fortran-interface.md
@@ -1,17 +1,16 @@
 ---
 project: RRTMGP-Fortran
 summary: RRTMGP is a correlated k-distribution for computing fluxes in earth's atmosphere.
-preprocessor: gfortran -E
+preprocess: false
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
 author: The RTE+RRTTMGP consortium
 github: https://github.com/earth-system-radiation/
 license: by
-title: RRTMGP Fortran interfaces
 src_dir: ../../rrtmgp-frontend
-output_dir: ../../public/reference/rrtmgp-fortran-interface
+output_dir: ../reference/rrtmgp-fortran-interface
 ---
 
 These pages provide a programmer's view of the Fortran user interface to RRTMGP.

diff --git a/doc/ford_site/rrtmgp-kernels.md → docs/ford_templates/rrtmgp-kernels.md b/doc/ford_site/rrtmgp-kernels.md → docs/ford_templates/rrtmgp-kernels.md
@@ -1,18 +1,19 @@
 ---
 project: RRTMGP kernels
 summary: RRTMGP is a correlated k-distribution for computing fluxes in earth's atmosphere.
-preprocessor: gfortran -E
+preprocess: false
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
 author: The RTE+RRTTMGP consortium
 github: https://github.com/earth-system-radiation/
 license: by
-title: RRTMGP kernels
 src_dir: ../../rrtmgp-kernels
-exclude_dir: ../../rrtmgp-kernels/accel ../../rrtmgp-kernels/api
-output_dir: ../../public/reference/rrtmgp-kernels
+exclude_dir:
+	../../rrtmgp-kernels/accel
+	../../rrtmgp-kernels/api
+output_dir: ../reference/rrtmgp-kernels
 ---
 
 These pages document the low-level computational kernels used by RRTMGP.

diff --git a/doc/ford_site/rte-fortran-interface.md → docs/ford_templates/rte-fortran-interface.md b/doc/ford_site/rte-fortran-interface.md → docs/ford_templates/rte-fortran-interface.md
@@ -1,17 +1,16 @@
 ---
 project: RTE-Fortran
 summary: RTE describes radiation problems in planetary atmospheres and computes radiative fluxes.
-preprocessor: gfortran -E
+preprocess: false
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
 author: The RTE+RRTTMGP consortium
 github: https://github.com/earth-system-radiation/
 license: by
-title: RTE Fortran interfaces-frontend
 src_dir: ../../rte-frontend
-output_dir: ../../public/reference/rte-fortran-interface
+output_dir: ../reference/rte-fortran-interface
 ---
 
 These pages provide a programmer's view of the Fortran user interface to RTE.

diff --git a/doc/ford_site/rte-kernels.md → docs/ford_templates/rte-kernels.md b/doc/ford_site/rte-kernels.md → docs/ford_templates/rte-kernels.md
@@ -1,18 +1,19 @@
 ---
 project: RTE kernels
 summary: RTE describes radiation problems in planetary atmospheres and computes radiative fluxes.
-preprocessor: gfortran -E
+preprocess: false
 display: public
 sort: permission-alpha
 graph: true
 md_extensions: markdown.extensions.toc
 author: The RTE+RRTTMGP consortium
 github: https://github.com/earth-system-radiation/
 license: by
-title: RTE kernels
 src_dir: ../../rte-kernels
-exclude_dir: ../../rte-kernels/accel ../../rte-kernels/api
-output_dir: ../../public/reference/rte-kernels
+exclude_dir:
+	../../rte-kernels/accel
+	../../rte-kernels/api
+output_dir: ../reference/rte-kernels
 ---
 
 These pages document the low-level computational kernels used by RRTMGP.

diff --git a/doc/jekyll_site/how-tos/build-and-test.md → docs/how-tos/build-and-test.md b/doc/jekyll_site/how-tos/build-and-test.md → docs/how-tos/build-and-test.md
diff --git a/doc/jekyll_site/how-tos/index.md → docs/how-tos/index.md b/doc/jekyll_site/how-tos/index.md → docs/how-tos/index.md
diff --git a/...kyll_site/how-tos/migrating-from-rrtmg.md → docs/how-tos/migrating-from-rrtmg.md b/...kyll_site/how-tos/migrating-from-rrtmg.md → docs/how-tos/migrating-from-rrtmg.md
diff --git a/doc/jekyll_site/index.markdown → docs/index.markdown b/doc/jekyll_site/index.markdown → docs/index.markdown
diff --git a/doc/jekyll_site/reference/compiler-flags.md → docs/reference/compiler-flags.md b/doc/jekyll_site/reference/compiler-flags.md → docs/reference/compiler-flags.md
diff --git a/.../reference/gas-concentrations-overview.md → .../reference/gas-concentrations-overview.md b/.../reference/gas-concentrations-overview.md → .../reference/gas-concentrations-overview.md
diff --git a/doc/jekyll_site/reference/index.md → docs/reference/index.md b/doc/jekyll_site/reference/index.md → docs/reference/index.md
diff --git a/..._site/reference/optical-props-overview.md → docs/reference/optical-props-overview.md b/..._site/reference/optical-props-overview.md → docs/reference/optical-props-overview.md
diff --git a/...site/reference/optical-props-src-funcs.md → docs/reference/optical-props-src-funcs.md b/...site/reference/optical-props-src-funcs.md → docs/reference/optical-props-src-funcs.md
diff --git a/doc/jekyll_site/reference/rrtmgp-overview.md → docs/reference/rrtmgp-overview.md b/doc/jekyll_site/reference/rrtmgp-overview.md → docs/reference/rrtmgp-overview.md
diff --git a/doc/jekyll_site/tutorials/index.md → docs/tutorials/index.md b/doc/jekyll_site/tutorials/index.md → docs/tutorials/index.md
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,3 +5,4 @@ _site @@
     .bundle
     vendor
     Gemfile.lock
+    **/.DS_Store