185 docs

.github/workflows/on-push.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
     - master
+    - 185-docs
     tags:
     - '*'
   pull_request:
@@ -110,25 +111,23 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Download combined environments
-      uses: actions/download-artifact@v4
+    - name: Configure Git Credentials
+      run: |
+        git config user.name github-actions[bot]
+        git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+    - uses: actions/setup-python@v5
       with:
-        name: combined-environments
-        path: ci
-    - name: Install Conda environment with Micromamba
-      uses: mamba-org/setup-micromamba@v1
+        python-version: 3.x
+    - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+    - uses: actions/cache@v4
       with:
-        environment-file: ci/combined-environment-ci.yml
-        environment-name: DEVELOP
-        cache-environment: true
-        create-args: >-
-          python=3.9
-    - name: Install package
-      run: |
-        python -m pip install --no-deps -e .
-    - name: Build documentation
-      run: |
-        make docs-build
+        key: mkdocs-material-${{ env.cache_id }}
+        path: .cache
+        restore-keys: |
+          mkdocs-material-
+    - run: pip install mkdocs-material mkdocs-glightbox
+    - name: deploy documentation
+      run: mkdocs gh-deploy --force
 
   integration-tests:
     needs: [combine-environments, unit-tests]

.pre-commit-config.yaml

@@ -6,6 +6,7 @@ repos:
   - id: end-of-file-fixer
   - id: check-json
   - id: check-yaml
+    args: ['--unsafe']
   - id: check-toml
   - id: debug-statements
   - id: mixed-line-ending
@@ -24,9 +25,11 @@ repos:
   - id: ruff
     args: [--fix, --show-fixes]
 - repo: https://github.com/executablebooks/mdformat
-  rev: 0.7.16
+  rev: 0.7.19
   hooks:
   - id: mdformat
+    additional_dependencies:
+    - mdformat-mkdocs[recommended]>=4.0.0
 - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
   rev: v2.9.0
   hooks:

Makefile

@@ -28,6 +28,6 @@ template-update:
 	pre-commit run --all-files cruft -c .pre-commit-config-cruft.yaml
 
 docs-build:
-	cd docs && rm -fr _api && make clean && make html
+	cd docs && bash make_docs.sh
 
 # DO NOT EDIT ABOVE THIS LINE, ADD COMMANDS BELOW

README.md

@@ -1,68 +1,70 @@
 # pyBDY
 
-[pyBDY documentation](http://pynemo.readthedocs.io/en/latest/index.html). To be updated soon.
+<img src="/docs/assets/icons/pybdy_logo_small.png" alt="pybdy_logo" width="100"/>
+
+[pyBDY documentation](https://noc-msm.github.io/pyBDY/).
 
 ## How do I get set up?
 
 These are the steps to take to install pyBDY:
 
 - Clone pyBDY repository:
 
-  ```
-  export PYBDY_DIR=$PWD/pyBDY
-  git clone https://github.com/NOC-MSM/pyBDY.git
-  ```
+    ```
+    export PYBDY_DIR=$PWD/pyBDY
+    git clone https://github.com/NOC-MSM/pyBDY.git
+    ```
 
 - Creating a specific conda virtual environment is highly recommended ([click here for more about virtual
-  enviroments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)).
-  Use the latest version of anaconda (to be added in your .bashrc or load the module in the command line, e.g ` module load anaconda/5-2021`).
+    enviroments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html)).
+    Use the latest version of anaconda (to be added in your .bashrc or load the module in the command line, e.g ` module load anaconda/5-2021`).
 
-  ```
-  cd $PYBDY_DIR
-  conda env create -n pybdy -f environment.yml python=3.9
-  ```
+    ```
+    cd $PYBDY_DIR
+    conda env create -n pybdy -f environment.yml python=3.9
+    ```
 
 - Activate the new virtual environment:
 
-  ```
-  conda activate pybdy
-  ```
+    ```
+    conda activate pybdy
+    ```
 
 - To deactivate (not now!):
 
-  ```
-  conda deactivate
-  ```
+    ```
+    conda deactivate
+    ```
 
 - Make sure the Java Runtime Environment is set e.g.:
 
-  ```
-  export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.372.b07-1.el7_9.x86_64/ # e.g. for livljobs\*
-  ```
+    ```
+    export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.372.b07-1.el7_9.x86_64/ # e.g. for livljobs\*
+    ```
 
-  Or (downloading from https://jdk.java.net/20/)
+    Or (downloading from https://jdk.java.net/20/)
 
-  ```
-  export JAVA_HOME=/Users/<username>/Downloads/jdk-20.0.1.jdk/Contents/Home/ # e.g. for mac OSX
-  ```
+    ```
+    export JAVA_HOME=/Users/<username>/Downloads/jdk-20.0.1.jdk/Contents/Home/ # e.g. for mac OSX
+    ```
 
-  Generalised methods for defining paths are as follows:
+    Generalised methods for defining paths are as follows:
 
-  ```
-  export JAVA_HOME=$(readlink -f $(which java)) # UNIX
-  export JAVA_HOME=$(/usr/libexec/java_home)    # Mac
+    ```
+    export JAVA_HOME=$(readlink -f $(which java)) # UNIX
+    export JAVA_HOME=$(/usr/libexec/java_home)    # Mac
 
-  ```
+    ```
 
-  NB the above may not land at the correct directory level, but should find
-  the correct root. PyBDY expects this to be the directory level with `lib`
-  in which might be e.g. 3 directories back.
+    NB the above may not land at the correct directory level, but should find
+    the correct root. PyBDY expects this to be the directory level with `lib`
+    in which might be e.g. 3 directories back.
 
 - Install pyBDY:
 
-  ```
-  pip install -e .
-  ```
+    ```
+    pip install -e .
+    ```
 
 This should result in pyBDY being installed in the virtual environment,
 and can be checked by entering:
@@ -109,57 +111,57 @@ The
 following steps are required,
 
 - Run pyBDY using the namelist file in the inputs folder
-  (namelist_local.bdy) from inside the root pyBDY directory, e.g.:
+    (namelist_local.bdy) from inside the root pyBDY directory, e.g.:
 
-  ```
-  cd $PYBDY_DIR
-  mkdir -p outputs
-  pybdy -s inputs/namelist_local.bdy
-  ```
+    ```
+    cd $PYBDY_DIR
+    mkdir -p outputs
+    pybdy -s inputs/namelist_local.bdy
+    ```
 
 - This will create two output files `coordinates.bdy.nc` and
-  `NNA_R12_bdyT_y1979_m11.nc` in an `./outputs` folder
+    `NNA_R12_bdyT_y1979_m11.nc` in an `./outputs` folder
 
 - To check the coordinates.bdy.nc has the correct boundary points, the
-  script `plotting/plot_coords.py` will plot the domain boundaries and show
-  the different locations of the rim width (increasing number should
-  go inwards).
+    script `plotting/plot_coords.py` will plot the domain boundaries and show
+    the different locations of the rim width (increasing number should
+    go inwards).
 
-  E.g.
-  `python plotting/plot_coords.py outputs/NNA_R12_bdyT_y1979m11.nc outputs/coordinates.bdy.nc`
-  ![Example plot_coords.py output](/screenshots/example_coords.png)
+    E.g.
+    `python plotting/plot_coords.py outputs/NNA_R12_bdyT_y1979m11.nc outputs/coordinates.bdy.nc`
+    ![Example plot_coords.py output](/screenshots/example_coords.png)
 
-  The other script `plot_bdy.py` plots extracted variables at the boundaries to help visualise the output (1D or 2D).
-  E.g.
-  `python plotting/plot_bdy.py outputs/NNA_R12_bdyT_y1979m11.nc votemper`
-  ![Example plot_bdy.py output](/screenshots/example_bdy_data.png)
+    The other script `plot_bdy.py` plots extracted variables at the boundaries to help visualise the output (1D or 2D).
+    E.g.
+    `python plotting/plot_bdy.py outputs/NNA_R12_bdyT_y1979m11.nc votemper`
+    ![Example plot_bdy.py output](/screenshots/example_bdy_data.png)
 
-  which also works on 2D tidal boundary data (note you can specify an output file name):
-  `python plotting/plot_bdy.py outputs/NNA_R12_bdytide_TPXO7p2_M2_grd_Z.nc z1 example_bdy_1d_data.png`
-  ![Example plot_bdy.py output for tides](/screenshots/example_bdy_1d_data.png)
+    which also works on 2D tidal boundary data (note you can specify an output file name):
+    `python plotting/plot_bdy.py outputs/NNA_R12_bdytide_TPXO7p2_M2_grd_Z.nc z1 example_bdy_1d_data.png`
+    ![Example plot_bdy.py output for tides](/screenshots/example_bdy_1d_data.png)
 
 ## Example: generating tidal boundary conditions on ARCHER2
 
 - Activate the new virtual environment:
 
-  ```
-  conda activate pybdy
-  ```
+    ```
+    conda activate pybdy
+    ```
 
 - Make sure all the directories and files are in place:
 
-  ```
-  cd pyBDY
-  mkdir outputs
-  ln -s /work/n01/n01/shared/jelt/FES2014 inputs/.
-  <cp benchmark dir into inputs/benchmark>
-  ```
+    ```
+    cd pyBDY
+    mkdir outputs
+    ln -s /work/n01/n01/shared/jelt/FES2014 inputs/.
+    <cp benchmark dir into inputs/benchmark>
+    ```
 
 - Press go:
 
-  ```
-  pybdy -s inputs/namelist_local.bdy
-  ```
+    ```
+    pybdy -s inputs/namelist_local.bdy
+    ```
 
 Take about 120s. Generates 7 consitutents, using FES2014 data, written
 to \`outputs\`:

contribution_guidelines.md

@@ -24,7 +24,7 @@ If you don't have write permissions on [NOC-MSM/pyBDY](https://github.com/NOC-MS
 
 1. Update the master branch of your local repository: `git checkout master && git pull`
 1. Open a GitHub issue or pick one already opened
-1. Create a branch that references the issue number and gives a summary of the changes that will be made:  `git branch issue-103-remove-pynemo-traces`
+1. Create a branch that references the issue number and gives a summary of the changes that will be made: `git branch issue-103-remove-pynemo-traces`
 1. Switch to that branch (i.e., update HEAD to set that branch as the current branch): `git checkout issue-103-remove-pynemo-traces`
 
 ## Stage and commit changes

docs/format_docs.py

@@ -0,0 +1,60 @@
+import glob
+
+markdown_files = glob.glob("./*.md")
+index_files = glob.glob("./index*.md")
+
+markdown_mods = list(set(markdown_files) - set(index_files))
+
+for i in range(len(markdown_mods)):
+    with open(markdown_mods[i], "r") as f:
+        data = f.readlines()
+
+    skip_ind = []
+    for j in range(len(data)):
+        # Swap args for parameters and remove colons
+        if "Arg" in data[j]:
+            data[j] = data[j].replace("s", "").replace("Arg", "Parameters")
+        if (
+            ("Parameters" in data[j]) | ("Returns" in data[j]) | ("Notes" in data[j])
+        ) & (":" in data[j]):
+            data[j] = data[j].replace(":", "")
+
+        # Upgrade some headings
+        if ("# " in data[j]) & ("package" not in data[j]) & ("##" not in data[j]):
+            data[j] = data[j].replace("# ", "")
+        if (" module" in data[j]) & ("## " in data[j]):
+            data[j] = data[j].replace("## ", "# ")
+        if (
+            ("### " in data[j])
+            & ("Parameters" not in data[j])
+            & ("Returns" not in data[j])
+            & ("Notes" not in data[j])
+        ):
+            data[j] = data[j].replace("### ", "## ")
+        data[j] = data[j].replace("#### ", "### ")
+        if ("Parameters" in data[j]) | ("Returns" in data[j]):
+            data[j] = "> " + data[j]
+        if (
+            ("### " in data[j])
+            & ("Parameters" not in data[j])
+            & ("Returns" not in data[j])
+            & ("Notes" not in data[j])
+        ):
+            data[j] = data[j].replace("### ", "### *method* ")
+
+        # Remove notes headings
+        if "## Notes" in data[j]:
+            skip_ind.append(j)
+
+        # Indent arguments
+        if (":" in data[j]) & (data[j][0] != ">"):
+            data[j] = "> " + data[j]
+        if data[j][0] == ">":
+            data[j] = data[j][:-1] + "<br>" + data[j][-1]
+
+    with open(markdown_mods[i], "w") as f:
+        for j in range(len(data)):
+            if len(skip_ind) > 0:
+                if j in skip_ind:
+                    continue
+            f.write(data[j])