Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 3 commits into from
Feb 23, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
77febc9
Add README and CONTRIBUTING.md to the doxygen pages.
samcunliffe Feb 16, 2023
27405bb
Split workflow into two jobs. Fix README inclusion.
samcunliffe Feb 22, 2023
466b4b3
Don't need that yet.
samcunliffe Feb 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 59 additions & 7 deletions .github/workflows/doxygen-gh-pages.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Comment on lines +3 to +8
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

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.
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
- 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
98 changes: 54 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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
Expand All @@ -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}
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
-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:
Expand All @@ -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...

Expand All @@ -98,22 +103,27 @@ Options:
-m: Minimise output file size by not saving vertex and facet information
willGraham01 marked this conversation as resolved.
Show resolved Hide resolved
```

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).
4 changes: 3 additions & 1 deletion doc/Doxyfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,5 +35,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