Add to Doxygen pages, and use doxygen as a CI check. (#231)

* Add README and CONTRIBUTING.md to the doxygen pages. * Split workflow into two jobs. Fix README inclusion. * Don't need that yet. Remove the copy of images.
UCL · Mar 24, 2023 · d49f363 · d49f363
1 parent c6a36d4
commit d49f363
Show file tree

Hide file tree

Showing 3 changed files with 116 additions and 52 deletions.
diff --git a/.github/workflows/doxygen-gh-pages.yml b/.github/workflows/doxygen-gh-pages.yml
@@ -1,15 +1,67 @@
-name: Doxygen GitHub Pages Deploy Action
+name: Run Doxygen and publish to GitHub pages
+
+# Generate the documentation on all merges to main, all pull requests, or by
+# manual workflow dispatch. The Doxygen job can be used as a CI check that all
+# functions are documented. The publish job only runs on new commits to the main
+# branch and actually pushes the generated html to the gh-pages branch (which
+# triggers a GitHub pages deployment). When things are a bit more stable, we can
+# only publish the website on release tags.
 on:
   push:
     branches:
       - main
+  pull_request:
   workflow_dispatch:
+
 jobs:
-  deploy:
+  doxygen:
+    runs-on: macos-latest
+    steps:
+
+    - name: Checkout repository
+      uses: actions/checkout@v3
+      with:
+        submodules: "true"
+
+    - name: Install Doxygen
+      run: brew install doxygen graphviz
+      shell: bash
+
+    - name: Run Doxygen
+      run: doxygen doc/Doxyfile
+      shell: bash
+
+    # Disabling jekyll ensures pages with underscores work on gh pages.
+    - name: Create .nojekyll
+      run: touch html/.nojekyll
+      shell: bash
+
+    - name: Upload the website
+      uses: actions/upload-artifact@v3
+      with:
+        name: tdms_website
+        path: html/*
+        retention-days: 1
+
+  publish:
     runs-on: ubuntu-latest
+    needs: doxygen
+    if: github.event_name == 'push' && github.ref_name == 'main'
     steps:
-      - uses: DenverCoder1/[email protected]
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          folder: html
-          config_file: doc/Doxyfile
+
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - name: Download the content for deployment
+      uses: actions/download-artifact@v3
+      with:
+        name: tdms_website
+        path: html
+        # Recreate and download to the html directory just for tidiness sake.
+
+    - name: Commit to GitHub Pages
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        branch: gh-pages
+        folder: html
diff --git a/README.md b/README.md
@@ -1,3 +1,9 @@
+<!-- \cond
+ -->
+<!-- 👆 this comment and the endcond below, tells doxygen to ignore the badges
+and title at the top of README.md when building the project page (the title
+would be duplicated) everything else in README.md is also the project homepage. -->
+
 [![Linux tests](https://github.com/UCL/TDMS/actions/workflows/linux_tests.yml/badge.svg)](https://github.com/UCL/TDMS/actions/workflows/linux_tests.yml)
 [![Windows tests](https://github.com/UCL/TDMS/actions/workflows/windows_tests.yml/badge.svg)](https://github.com/UCL/TDMS/actions/workflows/windows_tests.yml)
 [![MATLAB tests](https://github.com/UCL/TDMS/actions/workflows/matlab_tests.yml/badge.svg)](https://github.com/UCL/TDMS/actions/workflows/matlab_tests.yml)
@@ -8,16 +14,16 @@
 > **Warning**
 > This repository is a _work in progress_. The API will change without notice
 
-***
-## Introduction
+<!-- \endcond -->
+
+# Time-Domain Maxwell Solver
 
-TDMS, the Time Domain Maxwell Solver, is a hybrid C++ and MATLAB tool for solving
-Maxwell's equations to simulate light propagation through a medium. See the
-[pdf documentation](https://github.com/UCL/TDMS/blob/gh-doc/masterdoc.pdf) for
-further details.
+TDMS, the Time Domain Maxwell Solver, is a hybrid C++ and MATLAB tool for
+solving Maxwell's equations to simulate light propagation through a medium. See
+the [pdf documentation](https://github.com/UCL/TDMS/blob/gh-doc/masterdoc.pdf)
+for further details.
 
 
-***
 ## Compilation
 
 TDMS needs to be built against [FFTW](https://www.fftw.org/) and
@@ -34,45 +40,44 @@ $ cmake .. \
 # -DBUILD_TESTING=ON
 $ make install
 ```
-where lines need to be commented in and the paths modified if cmake cannot
-(1) find MATLAB, (2) find FFTW or (3) install to the default install prefix.
-
-- <details>
-    <summary>Mac specific instructions</summary>
-
-    To compile on a Mac an x86 compiler with libraries for OpenMP are required,
-    which can be installed using [brew](https://brew.sh/) with `brew install llvm`
-    then (optionally) set the following cmake arguments
-
-    ```
-    -DCMAKE_CXX_COMPILER=/Users/username/.local/homebrew/opt/llvm/bin/clang++
-    -DOMP_ROOT=/Users/username/.local/homebrew/opt/llvm/
-    -DCXX_ROOT=/Users/username/.local/homebrew/opt/llvm
-    ```
-
-    On an ARM Mac install the x86 version of brew with
-    ```bash
-    arch -x86_64 zsh
-    arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-    arch -x86_64 /usr/local/bin/brew install llvm
-    ```
+where lines need to be commented in and the paths modified if cmake cannot (1)
+find MATLAB, (2) find FFTW or (3) install to the default install prefix.
+
+<details>
+<summary>Mac specific instructions</summary>
+
+To compile on a Mac an x86 compiler with libraries for OpenMP are required,
+which can be installed using [brew](https://brew.sh/) with `brew install llvm`
+then (optionally) set the following cmake arguments
+
+```{sh}
+-DCMAKE_CXX_COMPILER=/Users/username/.local/homebrew/opt/llvm/bin/clang++
+-DOMP_ROOT=/Users/username/.local/homebrew/opt/llvm/
+-DCXX_ROOT=/Users/username/.local/homebrew/opt/llvm
+```
+
+On an ARM Mac install the x86 version of brew with
+```bash
+arch -x86_64 zsh
+arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+arch -x86_64 /usr/local/bin/brew install llvm
+```
 </details>
 
 
-***
 ## Usage
 
-Once the executable has been compiled and installed, `tdms` should be in the `PATH`.
-Check that installation worked with
+Once the executable has been compiled and installed, `tdms` should be in the
+`PATH`.  Check that installation worked with
 
 ```bash
 $ tdms -h
 ```
 
-You can invoke it directly or call it from a MATLAB script.
-We recommend that beginners with MATLAB installed start with the demonstration MATLAB script.
+You can invoke it directly or call it from a MATLAB script.  We recommend that
+beginners with MATLAB installed start with the demonstration MATLAB script.
 
-#### To run the demonstration code
+### To run the demonstration code
 
 Move into directory [`examples/arc_01`](./examples/arc_01/),
 launch MATLAB and run the MATLAB script:
@@ -82,7 +87,7 @@ launch MATLAB and run the MATLAB script:
 This script will generate the input to the executable, run the executable and
 display sample output.
 
-#### To run standalone
+### To run standalone
 
 You can also run `tdms` from the command line...
 
@@ -98,22 +103,27 @@ Options:
 -m:	Minimise output file size by not saving vertex and facet information
 ```
 
-The basic workflow is with two arguments, an input file as specified by [`iterate_fdtd_matrix.m`](./tdms/matlab/iteratefdtd_matrix.m), and an output file name to be created.
+The basic workflow is with two arguments, an input file as specified by
+[`iterate_fdtd_matrix.m`](./tdms/matlab/iteratefdtd_matrix.m), and an output
+file name to be created.
 
-You can choose two possible solver methods: either pseudo-spectral time-domain (PSTD, the default) or finite-difference (FDTD, with option `--finite-difference`).
+You can choose two possible solver methods: either pseudo-spectral time-domain
+(PSTD, the default) or finite-difference (FDTD, with option
+`--finite-difference`).
 
-#### Parallelism
+### Parallelism
 
-TDMS is parallelised with [OpenMP](https://en.wikipedia.org/wiki/OpenMP). The maximum
-number of threads can be set with the `OMP_NUM_THREADS` environment variable.
-For example, to use 4 threads, in a bash shell, use:
+TDMS is parallelised with [OpenMP](https://en.wikipedia.org/wiki/OpenMP). The
+maximum number of threads can be set with the `OMP_NUM_THREADS` environment
+variable.  For example, to use 4 threads, in a bash shell, use:
 
 ```bash
 $ export OMP_NUM_THREADS=4
 ```
 
 Before calling the `tdms` executable.
 
-## Contributing
+## Want to contribute?
 
-You are welcome to report new issues or submit pull requests.  For more information about how to contribute, please see the [`CONTRIBUTING.md`](./CONTRIBUTING.md) file and we have developer documentation on our [`gh-pages` site](https://github-pages.ucl.ac.uk/TDMS).
+We're very grateful for bug reports, feature requests and pull requests. Please
+see our [contribution guidelines](./CONTRIBUTING.md).
diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -40,5 +40,7 @@ GENERATE_TREEVIEW      = YES
 HTML_EXTRA_STYLESHEET  = doc/doxygen-awesome-css/doxygen-awesome.css
 
 # 'mainpage' gets put on the index page
+INPUT += README.md
+INPUT += CONTRIBUTING.md
 INPUT += doc/developers.md
-USE_MDFILE_AS_MAINPAGE = doc/developers.md
+USE_MDFILE_AS_MAINPAGE = README.md