Merge pull request #178 from mach3-software/feature_auto_sphinx_docs

Auto generation python docs
mach3-software · Oct 23, 2024 · 3eef1d4 · 3eef1d4
2 parents daa631e + 627fb46
commit 3eef1d4
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 14 deletions.
diff --git a/.github/workflows/Doxygen.yml b/.github/workflows/Doxygen.yml
@@ -1,17 +1,21 @@
-# This is a basic workflow make doxygen documentation every time develop is updated
+---
+# This is a basic workflow make doxygen documentation 
+# every time develop is updated
 
 name: Doxygen
 
 # Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the develop branch
+  # Triggers the workflow on push or pull request events 
+  # but only for the develop branch
   push:
-    branches: [ develop ]
+    branches: [develop]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+# A workflow run is made up of one or more jobs that can run 
+# sequentially or in parallel
 jobs:
   # This workflow contains a single job called "Doxygen"
 
@@ -23,9 +27,11 @@ jobs:
       contents: write
       id-token: write
 
-    # Steps represent a sequence of tasks that will be executed as part of the job
+    # Steps represent a sequence of tasks that will be executed
+    # as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      # Checks-out your repository under $GITHUB_WORKSPACE, 
+      # so your job can access it
       - uses: actions/checkout@v4
 
       # Updates the package list to ensure you get the latest version of packages
@@ -34,7 +40,8 @@ jobs:
       # Installs texlive for LaTeX support in Doxygen documentation
       - run: sudo apt-get install -y texlive
 
-      # Installs libjs-mathjax for rendering mathematical notation in Doxygen documentation
+      # Installs libjs-mathjax for rendering mathematical notation 
+      # in Doxygen documentation
       - run: sudo apt-get install -y libjs-mathjax
 
       # Install perl for bibtex
@@ -46,11 +53,80 @@ jobs:
         with:
           doxyfile-path: './Doxyfile'
           working-directory: ./Doc
-
-      # Deploys the generated documentation to GitHub Pages
-      - name: Deploy
-        uses: peaceiris/actions-gh-pages@v4
+
+      - name: Upload Doxygen Artifact
+        uses: actions/upload-artifact@v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./Doc/html
+          retention-days: 1
+          name: DoxygenHTML
+          path: Doc/html
+
+  Sphinx:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    container:
+      image: ghcr.io/mach3-software/mach3:alma9latest
+
+    needs: Doxygen
+
+    steps:
 
+      # Checks-out your repository under $GITHUB_WORKSPACE, 
+      # so your job can access it
+      - uses: actions/checkout@v4
+
+      - name: Check Python 
+        run: python3 --version
+
+      - name: Download Doxygen Artifact
+        uses: actions/download-artifact@master
+        with:
+          name: DoxygenHTML
+          path: to-upload/
+
+      ## EM: Now we delete the artifact so it doesn't use up our allowance
+      - uses: geekyeggo/delete-artifact@v5
+        with:
+          name: DoxygenHTML
+
+      - name: Build MaCh3
+        run: | 
+          mkdir build
+          cd build 
+          cmake -DMaCh3_PYTHON_ENABLED=ON ../
+          make -j4
+          make install
+          
+      ## EM: Now generate the sphinx documentation
+      - name: Sphinx Build    
+        working-directory: Doc/sphinx
+        run: | 
+          source ../../build/bin/setup.MaCh3.sh
+          python3 -m venv sphinx_env 
+          source sphinx_env/bin/activate 
+          pip install -r requirements.txt 
+          make html
+          
+      ## EM: Move the generated sphinx docs into the final html folder
+      - name: Move Sphinx Docs
+        run: |
+          mkdir to-upload/pyMaCh3
+          mv Doc/sphinx/build/html/* to-upload/pyMaCh3/
+          
+      - uses: actions/upload-artifact@v4
+        with:
+          retention-days: 1
+          name: DocumentationHTML
+          path: to-upload
+
+  #Deploy:
+  #  runs-on: ubuntu-latest
+  #  needs: [Doxygen, Sphinx]
+
+      # Deploys the generated documentation to GitHub Pages
+      #- name: Deploy
+      #  uses: peaceiris/actions-gh-pages@v4
+      #  with:
+      #    github_token: ${{ secrets.GITHUB_TOKEN }}
+      #    publish_dir: ./to-upload/html
diff --git a/Doc/mainpage.md b/Doc/mainpage.md
@@ -1,4 +1,4 @@
-\mainpage %MaCh3 Reference Documentation
+# MaCh3
 
 ## Introduction
 Welcome to %MaCh3!
@@ -9,6 +9,8 @@ You can find additional documentation on our [Wiki](https://github.com/mach3-sof
 
 If you are new we recommend to start from our [Tutorial](https://github.com/mach3-software/MaCh3Validations)
 
+MaCh3 also comes with a Python interface. You can find out more about this in the dedicated [pyMaCh3 documentation](./pyMach3/mainpage.html)
+
 If something is unclear please contact us via
 - [Mailing lists](https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=MACH3)
 - [Slack](https://t2k-experiment.slack.com/archives/C06EM0C6D7W/p1705599931356889)