Merge pull request #100 from British-Oceanographic-Data-Centre/develop

Merge new documentation to master
British-Oceanographic-Data-Centre · Dec 8, 2023 · 5c2de44 · 5c2de44
2 parents 90326dd + 2b0bf9a
commit 5c2de44
Show file tree

Hide file tree

Showing 130 changed files with 3,675 additions and 2,620 deletions.
diff --git a/.github/workflows/docstrings.yml b/.github/workflows/docstrings.yml
@@ -11,23 +11,23 @@ jobs:
     runs-on: ubuntu-20.04
     steps:
       - name: Checkout site
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive # Fetch Hugo themes and all extra projects
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
           path: site
 
       - name: Checkout coast
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: British-Oceanographic-Data-Centre/COAsT
           ref: develop
           path: external
 
       - name: add python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.8
+          python-version: 3.10
 
       - name: covert docstrings
         run: |
@@ -44,8 +44,10 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global author.email "[email protected]"
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY
+          git fetch origin
           git checkout develop
           git pull
+          [ ! -f content/en/docs/Reference/index.md ] || mv content/en/docs/Reference/index.md content/en/docs/Reference/index_class.md
           git add content/en/docs/Reference/*
           git commit -am "Updated docstrings from coast repo."
           git push origin develop

diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml
@@ -9,19 +9,19 @@ jobs:
   deploy:
     runs-on: ubuntu-20.04
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           submodules: recursive  # Fetch Hugo themes and all extra projects
           fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
 
       - name: Setup Hugo
         uses: peaceiris/actions-hugo@v2
         with:
-          hugo-version: '0.70.0'
+          hugo-version: '0.120.1'
           extended: true
 
       - name: Setup nodejs 
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
           node-version: 12               
 

diff --git a/.github/workflows/markdown-altimetry.yml b/.github/workflows/markdown-altimetry.yml
@@ -14,14 +14,14 @@ jobs:
         shell: bash -l {0}
     steps:
       - name: Checkout site
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive # Fetch Hugo themes and all extra projects
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
           path: site
 
       - name: Checkout coast
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: British-Oceanographic-Data-Centre/COAsT
           ref: develop
@@ -32,7 +32,6 @@ jobs:
         with:
           activate-environment: coast
           environment-file: external/environment.yml
-          python-version: 3.8.10
       - name: prep exec notebooks
         run: |
           conda info
@@ -67,6 +66,7 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global author.email "[email protected]"
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY
+          git fetch origin
           git checkout develop
           git pull        
           git add content/en/docs/Examples/Notebooks/Altimetry/*

diff --git a/.github/workflows/markdown-general.yml b/.github/workflows/markdown-general.yml
@@ -13,14 +13,14 @@ jobs:
         shell: bash -l {0}
     steps:
       - name: Checkout site
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive # Fetch Hugo themes and all extra projects
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
           path: site
 
       - name: Checkout coast
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: British-Oceanographic-Data-Centre/COAsT
           ref: develop
@@ -31,7 +31,6 @@ jobs:
         with:
           activate-environment: coast
           environment-file: external/environment.yml
-          python-version: 3.8.10
       - name: prep exec notebooks
         run: |
           conda info
@@ -45,6 +44,9 @@ jobs:
           mkdir -p ./example_scripts/notebook_tutorials/markdown/general
           ls ./example_scripts/notebook_tutorials
           pip install .
+          sudo apt-get update
+          sudo apt-get install -y libgeos-dev
+          pip install cartopy==0.21.0
           mv config ./example_scripts/notebook_tutorials/runnable_notebooks/general/config
           bash notebook_to_md.sh general
       - name: convert notebooks 
@@ -58,6 +60,8 @@ jobs:
           mv ./markdown/general/climatology_tutorial.md $GITHUB_WORKSPACE/site/content/en/docs/Examples/Notebooks/General/
           mv ./markdown/general/dask_wrapper_template_tutorial.md $GITHUB_WORKSPACE/site/content/en/docs/Examples/Notebooks/General/
           mv ./markdown/general/mask_maker_tutorial.md $GITHUB_WORKSPACE/site/content/en/docs/Examples/Notebooks/General/
+          mv ./markdown/general/polar_plotting.md $GITHUB_WORKSPACE/site/content/en/docs/Examples/Notebooks/General/
+          mv ./markdown/general/zarr_files.md $GITHUB_WORKSPACE/site/content/en/docs/Examples/Notebooks/General/
           echo "Move images"
           rsync -r ./markdown_images/general/ $GITHUB_WORKSPACE/site/static
           
@@ -69,8 +73,9 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global author.email "[email protected]"
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY
+          git fetch origin
           git checkout develop
-          git pull        
+          git pull
           git add content/en/docs/Examples/Notebooks/General/*
           git add static/*
           git commit -am "Updated General notebook pages from coast repo."

diff --git a/.github/workflows/markdown-gridded.yml b/.github/workflows/markdown-gridded.yml
@@ -13,14 +13,14 @@ jobs:
         shell: bash -l {0}
     steps:
       - name: Checkout site
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive # Fetch Hugo themes and all extra projects
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
           path: site
 
       - name: Checkout coast
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: British-Oceanographic-Data-Centre/COAsT
           ref: develop
@@ -31,7 +31,6 @@ jobs:
         with:
           activate-environment: coast
           environment-file: external/environment.yml
-          python-version: 3.8.10
       - name: prep exec notebooks
         run: |
           conda info
@@ -71,8 +70,9 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global author.email "[email protected]"
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY
+          git fetch origin
           git checkout develop
-          git pull        
+          git pull
           git add content/en/docs/Examples/Notebooks/Gridded/*
           git add static/*
           git commit -am "Updated Gridded notebook pages from coast repo."

diff --git a/.github/workflows/markdown-profile.yml b/.github/workflows/markdown-profile.yml
@@ -13,14 +13,14 @@ jobs:
         shell: bash -l {0}
     steps:
       - name: Checkout site
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive # Fetch Hugo themes and all extra projects
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
           path: site
 
       - name: Checkout coast
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: British-Oceanographic-Data-Centre/COAsT
           ref: develop
@@ -31,7 +31,6 @@ jobs:
         with:
           activate-environment: coast
           environment-file: external/environment.yml
-          python-version: 3.8.10
       - name: prep exec notebooks
         run: |
           conda info
@@ -64,6 +63,7 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global author.email "[email protected]"
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY
+          git fetch origin
           git checkout develop
           git pull        
           git add content/en/docs/Examples/Notebooks/Profile/*

diff --git a/.github/workflows/markdown-tidegauge.yml b/.github/workflows/markdown-tidegauge.yml
@@ -13,14 +13,14 @@ jobs:
         shell: bash -l {0}
     steps:
       - name: Checkout site
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           submodules: recursive # Fetch Hugo themes and all extra projects
           fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
           path: site
 
       - name: Checkout coast
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: British-Oceanographic-Data-Centre/COAsT
           ref: develop
@@ -31,7 +31,6 @@ jobs:
         with:
           activate-environment: coast
           environment-file: external/environment.yml
-          python-version: 3.8.10
       - name: prep exec notebooks
         run: |
           conda info
@@ -67,6 +66,7 @@ jobs:
           git config --global user.email "[email protected]"
           git config --global author.email "[email protected]"
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY
+          git fetch origin
           git checkout develop
           git pull        
           git add content/en/docs/Examples/Notebooks/Tidegauge/*

diff --git a/README.md b/README.md
@@ -1,31 +1,53 @@
-# COAsT docsy
+# COAsT Documentation Website
 
-This is the website repo for the COAsT python package it uses [Docsy](https://github.com/google/docsy) a Hugo theme for technical documentation sites, providing easy site navigation, structure, and more.
+This is the repository for the COAsT Python package documentation website. This site utilizes the [Docsy](https://github.com/google/docsy) theme, a Hugo theme designed for technical documentation sites, offering streamlined navigation, structure, and more.
 
+## Prerequisites
 
-## Cloning the COAsT Project website
+Before you get started, make sure you have the following prerequisites in place:
 
-The following will give you a project that is set up and ready to use (don't forget to use `--recurse-submodules` or you won't pull down some of the code you need to generate a working site). The `hugo server` command builds and serves the site. If you just want to build the site, run `hugo` instead.
+1. **Node.js and npm Installation**: Download and install Node.js, which includes npm, from the official [Node.js website](https://nodejs.org/). We recommend using version 18 or later.
+
+2. **Hugo Installation**: You'll need an extended version of Hugo, preferably version 0.120.1 or later, for local builds and previews of sites that use Docsy. To ensure you have the correct Hugo version, follow these steps:
+
+   - If you install Hugo from the release page, make sure to select the **extended Hugo version** to support SCSS.
+
+   - After installation, verify your Hugo version by running `hugo version`. Your output should resemble the following:
+
+     ```bash
+     hugo v0.120.2-9c2b2414d231ec1bdaf3e3a030bf148a45c7aa17+extended linux/amd64 BuildDate=2023-10-31T16:27:18Z VendorInfo=gohugoio
+     ```
+
+     Ensure that the version name includes the string *"extended"*.
+
+## Getting Started
+
+Follow these steps to set up your project and get it ready for use. Begin by cloning the repository:
 
 ```bash
-git clone --recurse-submodules --depth 1 https://github.com/British-Oceanographic-Data-Centre/COAsT-site.git
-cd docsy-example
-hugo server
+git clone --recurse-submodules --depth 1 [email protected]:British-Oceanographic-Data-Centre/COAsT-site.git
+cd COAsT-site
 ```
 
-The theme is included as a Git submodule:
+Now, proceed to install the dependencies and essential scripts:
 
 ```bash
-▶ git submodule
- a053131a4ebf6a59e4e8834a42368e248d98c01d themes/docsy (heads/master)
+npm install      # Install package dependencies 
+npm run prepare  # Fetch the submodule used as the theme for this website and install its dependencies
 ```
 
-If you want to do SCSS edits and want to publish these, you need to install `PostCSS` (not needed for `hugo server`):
+The `npm run prepare` command will install all the necessary dependencies for your theme, including `PostCSS`, `Bootstrap`, and `Autoprefixer`.
+
+## Running the Website Locally
+
+After cloning the site repository, navigate to the repository's root folder, and execute the following command to serve the website locally:
 
 ```bash
-npm install
+hugo server
 ```
 
+The `hugo server` command builds and serves the site. If you only want to build the site without serving it locally, run `hugo` instead.
+
 <!--### Cloning the Example from the Theme Project
 
 
@@ -42,12 +64,4 @@ Note that the Hugo Theme Site requires the `exampleSite` to live in a subfolder
 git subtree add --prefix exampleSite https://github.com/google/docsy.git  master --squash
 ```
 
-To pull in changes, see `pull-deps.sh` script in the theme.-->
-
-## Running the website locally
-
-Once you've cloned the site repo, from the repo root folder, run:
-
-```
-hugo server
-```
+To pull in changes, see `pull-deps.sh` script in the theme.-->
diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss
@@ -4,3 +4,50 @@ Add styles or override variables from the theme here.
 
 */
 
+.text-shadow-black-3{
+  text-shadow: 3px 3px rgba(0,0,0,1);
+}
+.text-shadow-black-2{
+  text-shadow: 2px 2px rgba(0,0,0,1);
+}
+
+.text-shadow-white-3{
+  text-shadow: 3px 3px rgba(255,255,255,1);
+}
+.text-shadow-white-2{
+  text-shadow: 2px 2px rgba(255,255,255,1);
+}
+
+.link-size{
+  width: 12rem;
+}
+
+.icon-size{
+  height: 2rem;
+}
+
+.foot-link{
+  :hover{
+    opacity: 0.7;
+  }
+}
+
+.td-search__input:not(:focus){
+  background: rgba(0,0,0,0.3) !important;
+}
+
+
+.td-footer {
+  min-height: 130px !important;
+  padding-top: 2.5rem !important;
+}
+
+
+#td-cover-block-0 {
+  background-image: linear-gradient(45deg, rgba(255,255,255, 0.2), rgba(255,255,255, 0.2)), url(/COAsT/feature-background_hu7bd19a57cd689ada407cd31cc8f06f38_227588_960x540_fill_q75_catmullrom_top.jpg) !important;
+}
+@media only screen and (min-width: 1200px) {
+  #td-cover-block-0 {
+    background-image: linear-gradient(45deg, rgba(255,255,255, 0.2), rgba(255,255,255, 0.2)), url(/COAsT/feature-background_hu7bd19a57cd689ada407cd31cc8f06f38_227588_960x540_fill_q75_catmullrom_top.jpg)  !important;
+  }
+}