Merge pull request #21 from nsidc/docs

Docs website and structure for interface documentation and design

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+# Build, and deploy docs to GitHub Pages
+name: "Build and deploy docs"
+
+on:
+  # "Production" deployments run on branch
+  push:
+    branches: ["main"]
+    paths:
+      - "doc/**"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+
+# Sets permissions of the GITHUB_TOKEN
+permissions:
+  # For GitHub Pages:
+  contents: "read"
+  pages: "write"
+  id-token: "write"
+
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+
+jobs:
+  # Build job
+  build:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v3"
+
+      - uses: "quarto-dev/quarto-actions/setup@v2"
+
+      - name: "Render Quarto website"
+        run: "quarto render ."
+
+      - name: "Upload site artifact"
+        uses: "actions/upload-pages-artifact@v1"
+        with:
+          path: "./_site"
+
+
+  # Deploy to GH Pages
+  deploy:
+    runs-on: "ubuntu-latest"
+    needs: "build"
+    environment:
+      name: "github-pages"
+      url: "${{ steps.deployment.outputs.page_url }}"
+    steps:
+      - name: "Deploy to GitHub Pages"
+        id: "deployment"
+        uses: "actions/deploy-pages@v1"

doc/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+/_site/

doc/_extensions/quarto-ext/include-code-files/_extension.yml

@@ -0,0 +1,9 @@
+title: Include Code Files
+author: Bruno Beaufils
+version: 1.0.0
+quarto-required: ">=1.2"
+contributes:
+  filters:
+    - include-code-files.lua
+
+

doc/_extensions/quarto-ext/include-code-files/include-code-files.lua

@@ -0,0 +1,63 @@
+--- include-code-files.lua – filter to include code from source files
+---
+--- Copyright: © 2020 Bruno BEAUFILS
+--- License:   MIT – see LICENSE file for details
+
+--- Dedent a line
+local function dedent (line, n)
+  return line:sub(1,n):gsub(" ","") .. line:sub(n+1)
+end
+
+--- Filter function for code blocks
+local function transclude (cb)
+  if cb.attributes.include then
+    local content = ""
+    local fh = io.open(cb.attributes.include)
+    if not fh then
+      io.stderr:write("Cannot open file " .. cb.attributes.include .. " | Skipping includes\n")
+    else
+      local number = 1
+      local start = 1
+
+      -- change hyphenated attributes to PascalCase
+      for i,pascal in pairs({"startLine", "endLine"})
+      do
+         local hyphen = pascal:gsub("%u", "-%0"):lower()
+         if cb.attributes[hyphen] then
+            cb.attributes[pascal] = cb.attributes[hyphen]
+            cb.attributes[hyphen] = nil
+         end
+      end
+
+      if cb.attributes.startLine then
+        cb.attributes.startFrom = cb.attributes.startLine
+        start = tonumber(cb.attributes.startLine)
+      end
+      for line in fh:lines ("L")
+      do
+        if cb.attributes.dedent then
+          line = dedent(line, cb.attributes.dedent)
+        end
+        if number >= start then
+          if not cb.attributes.endLine or number <= tonumber(cb.attributes.endLine) then
+            content = content .. line
+          end
+        end
+        number = number + 1
+      end 
+      fh:close()
+    end     
+    -- remove key-value pair for used keys
+    cb.attributes.include = nil
+    cb.attributes.startLine = nil
+    cb.attributes.endLine = nil
+    cb.attributes.dedent = nil
+    -- return final code block
+    return pandoc.CodeBlock(content, cb.attr)
+  end
+end
+
+return {
+  { CodeBlock = transclude }
+}
+

doc/_quarto.yml

@@ -0,0 +1,42 @@
+project:
+  type: "website"
+
+
+website:
+  title: "Snow Today Webapp Server Docs"
+  site-url: "https://nsidc.github.io/snow-today-webapp-server"
+  repo-url: "https://github.com/nsidc/snow-today-webapp-server"
+  repo-actions:
+    - "edit"
+    - "source"
+    - "issue"
+
+  page-footer:
+    right: "This page is built with [Quarto](https://quarto.org/)."
+    left: "© NSIDC"
+
+  sidebar:
+    background: "#eee"
+    style: "docked"
+    search: true
+    contents:
+      - section: "Interfaces"
+        contents:
+          - text: "Supercomputer data"
+            href: "interfaces/supercomputer_data/index.md"
+            contents:
+              - text: "Drafts"
+                href: "interfaces/supercomputer_data/drafts/index.md"
+          - text: "Webapp data"
+            href: "interfaces/webapp_data/index.md"
+      - section: "Ingest"
+        contents:
+          - text: "TODO"
+            href: "index.md"
+
+
+format:
+  html:
+    theme: "cosmo"
+    css: "styles.css"
+    toc: true

doc/environment.yml

@@ -0,0 +1,6 @@
+name: "snow-today-webapp-server-docs"
+channels:
+  - "conda-forge"
+  - "nodefaults"
+dependencies:
+  - "quarto"

doc/index.md

@@ -0,0 +1,5 @@
+---
+title: "Snow Today Webapp Server Docs"
+---
+
+This is the docs for the Snow Today Webapp Server

doc/interfaces/supercomputer_data/drafts/20231009_region_hierarchy/index.md

@@ -0,0 +1,78 @@
+---
+title: "Region Hierarchy JSON Specification"
+date: "2023-10-09"
+author: "Sebastien Lenard"
+filters:
+  - "include-code-files"
+---
+
+This is our first draft.
+
+## Requirements
+
+We're trying to balance all of these concerns:
+
+- Webapp load times
+- Webapp usability
+- Flexibility to change front-end behavior by pushing different data from the
+  supercomputer.
+- Predictability in how the front-end will handle data changes (why we need a spec!)
+
+
+## Specification
+
+### Super regions
+
+Super regions are listed in their own JSON file. These are the highest-level regions,
+e.g. `US West`, `Alaska`, etc.
+
+The webapp needs to be able to quickly load the list of super-regions so it can display
+the super-region dropdown. Depending on which is selected, different sub-regions may
+display.
+
+This file will contain information about each super region:
+
+- id
+- short name
+- long name
+
+... TODO ...
+
+
+### Sub regions
+
+Any region that's not a super-region. There is one JSON file for each super region's sub
+regions. E.g. `WesternUS/regions.json`.
+
+This file will contain information about each region:
+
+- id
+- short name
+- long name
+
+
+... TODO ...
+
+
+#### Sub region hierarchy
+
+Sub regions fall in to a hierarchy, for example one HUC2 has many HUC4s.
+
+... TODO ...
+
+- How will we define metadata about collections of subregions? E.g. longname / shortname
+  for collections (`HUC 2`/`Hydrologic Unit Code 2 (2 digits)`). In this case, there
+  will be _many_ HUC4 collections each within a separate HUC2 collection, and we don't
+  want to repeat that information.
+
+
+## Examples
+
+<details>
+<summary>`region_hierarchy.json`</summary>
+I believe this example doesn't quite fit with the specification outline above yet, it's
+just an early draft.
+
+```{.json include="regions.json"}
+```
+</details>