Render docs with Quarto using ReadTheDocs

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python
+    python: "mambaforge-22.9"
+  commands:
+    - "conda install quarto~=1.3.450"
+    - "cd doc && quarto render"
+    - "mv doc/_site/* $READTHEDOCS_OUTPUT/html/."

doc/.gitignore

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

doc/_quarto.yml

@@ -0,0 +1,40 @@
+project:
+  type: "website"
+
+
+website:
+  title: "US AON Benefit Tool"
+  site-url: "https://nsidc.github.io/usaon-benefit-tool"
+
+  repo-url: "https://github.com/nsidc/usaon-benefit-tool"
+  repo-actions:
+    - "edit"
+    - "source"
+    - "issue"
+
+
+  page-footer:
+    right: "This page is built with [Quarto](https://quarto.org/)."
+    left: "©"
+
+  sidebar:
+    style: "docked"
+    search: true
+    contents:
+      - text: "How to"
+        href: "how-to/index.md"
+      - text: "Reference"
+        href: "reference/index.md"
+
+      # Separator:
+      - text: "---"
+
+      - text: "Notes"
+        href: "notes/index.md"
+
+
+format:
+  html:
+    from: "markdown+emoji"
+    theme: ["cosmo", "style.scss"]
+    toc: true

doc/db.md → doc/how-to/db.md

@@ -1,5 +1,4 @@
-# Database
-
+# Database setup
 
 It's expected that you'll set up a DB separately from the app. The app uses a proxy
 container to enable it to talk to an external DB through the hostname `db`.

doc/development.md → doc/how-to/development.md

@@ -12,7 +12,7 @@ ln -s docker-compose.dev.yml docker-compose.override.yml
 
 ### Define environment variables
 
-Define the environment variables as specified in [envvars.md](./envvars.md):
+Define the environment variables as specified in [envvars.md](/reference/envvars.md):
 
 ```bash
 export USAON_VTA_DB_HOST=...

doc/how-to/index.md

@@ -0,0 +1,6 @@
+---
+listing:
+  type: "table"
+  fields:
+    - "title"
+---

doc/index.md

@@ -0,0 +1,8 @@
+---
+title: "US Arctic Observing Network Benefit Tool"
+subtitle: "Software documentation"
+---
+
+:::{.callout-important}
+For user documentation, please see https://usaon.org/evaluation-and-planning/benefit-tool
+:::

doc/TODO.md → doc/notes/TODO.md

@@ -1,3 +1,7 @@
-# Templates
+---
+title: "TODO"
+---
+
+## Templates
 
 * Should Jinja templates have a `.html` or `.j2` extension?

doc/notes/index.md

@@ -0,0 +1,6 @@
+---
+listing:
+  type: "table"
+  fields:
+    - "title"
+---

doc/reference/index.md

@@ -0,0 +1,6 @@
+---
+listing:
+  type: "table"
+  fields:
+    - "title"
+---