Documentation setup (#179)

carbonplan · May 12, 2022 · 84b81ec · 84b81ec · vercel · May 12, 2022
1 parent 5dc9a32
commit 84b81ec
Show file tree

Hide file tree

Showing 13 changed files with 92 additions and 52 deletions.
diff --git a/.gitignore b/.gitignore
@@ -129,3 +129,7 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+node_modules/
+.next/
+generated/
diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,38 @@
+# API
+
+```{eval-rst}
+.. currentmodule:: cmip6_downscaling
+```
+
+## Data
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   data.cmip.postprocess
+   data.cmip.load_cmip
+   data.cmip.get_gcm
+
+   data.observations.open_era5
+
+   data.utils.to_standard_calendar
+   data.utils.lon_to_180
+```
+
+## Downscaling Methods
+
+```{eval-rst}
+.. currentmodule:: cmip6_downscaling.methods
+```
+
+### BCSD
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated/
+
+   bcsd.tasks.spatial_anomalies
+   bcsd.tasks.fit_and_predict
+   bcsd.tasks.postprocess_bcsd
+```
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -36,6 +36,7 @@
     "numpydoc",
     "IPython.sphinxext.ipython_directive",
     "IPython.sphinxext.ipython_console_highlighting",
+    "myst_parser",
 ]
 
 autosummary_generate = True
@@ -67,7 +68,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = ["_build", "node_modules"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"

diff --git a/docs/deploy.sh → docs/create-mamba-env.sh b/docs/deploy.sh → docs/create-mamba-env.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-set -x
+set -xe
 
 # install mamba
 yum install -y wget bzip2
@@ -10,9 +10,4 @@ source ~/.bashrc
 
 # install python deps
 micromamba create -y -f ./environment.yml
-micromamba activate docs
-pip install ..
-
-# build json content
-make json
-ls _build/json/*
+micromamba activate cmip6-downscaling-docs
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -1,4 +1,4 @@
-name: docs
+name: cmip6-downscaling-docs
 channels:
   - conda-forge
   - nodefaults
@@ -10,7 +10,29 @@ dependencies:
   - setuptools
   - sphinx
   - numpydoc
+  - myst-nb
   # this project's dependencies
+  - adlfs
+  - dask
+  - dask-kubernetes
+  - donfig
+  - fsspec
+  - gcsfs
+  - intake-esm
+  - intake-xarray
   - numpy
   - pandas
+  - prefect
+  - regionmask
+  - scikit-downscale
+  - scikit-learn
   - scipy
+  - xclim
+  - xpersist
+  - zarr
+  - universal_pathlib
+  - ndpyramid
+  - pip:
+      - git+https://github.com/carbonplan/xarray-schema
+      - carbonplan-data
+      - -e ..
diff --git a/docs/make-sphinx-json.sh b/docs/make-sphinx-json.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -xe
+
+source ~/.bashrc
+
+micromamba activate cmip6-downscaling-docs
+
+# build json content
+make json
+ls _build/json/*
diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/package.json b/docs/package.json
@@ -4,9 +4,12 @@
   "description": "",
   "main": "index.js",
   "scripts": {
+    "create-mamba-env": "bash create-mamba-env.sh",
+    "make-sphinx-json": "bash make-sphinx-json.sh",
     "dev": " NODE_ENV=development next",
     "start": "next start",
-    "build": "bash deploy.sh && next build"
+    "build": "npm run create-mamba-env && npm run make-sphinx-json && next build",
+    "devbuild": "next build"
   },
   "author": "",
   "license": "MIT",
@@ -18,7 +21,7 @@
     "@mdx-js/loader": "^1.6.22",
     "@mdx-js/react": "^1.6.22",
     "@next/mdx": "^12.0.7",
-    "html-to-react": "^1.4.7",
+    "html-to-react": "^1.4.8",
     "next": "^12.0.7",
     "react": "^17.0.2",
     "react-dom": "^17.0.2",

diff --git a/docs/pages/cmip6-downscaling/how-to-guide.md b/docs/pages/cmip6-downscaling/how-to-guide.md
@@ -4,7 +4,4 @@ import Section from '../../components/section'
 
 Text here...
 
-export default ({ children }) => (
-
-  <Section name='How-to Guide'>{children}</Section>
-)
+export default ({ children }) => <Section name='How-to Guide'>{children}</Section>
diff --git a/docs/pages/cmip6-downscaling/quick-start.md b/docs/pages/cmip6-downscaling/quick-start.md
@@ -31,7 +31,4 @@ The `cmip6-downscaling` package provides a number of downscaling implementations
 import cmip6_downscaling
 ```
 
-export default ({ children }) => (
-
-  <Section name='Quick Start'>{children}</Section>
-)
+export default ({ children }) => <Section name='Quick Start'>{children}</Section>
diff --git a/docs/pages/cmip6-downscaling/running-flows.md b/docs/pages/cmip6-downscaling/running-flows.md
@@ -1,3 +1,5 @@
+import Section from '../../components/section'
+
 # Running Prefect Flows
 
 ## Why Prefect
@@ -157,3 +159,5 @@ Note: This url is specific to username, jupyter-hub name and port.
 ex:
 
 `https://prod.azure.carbonplan.2i2c.cloud/user/norlandrhagen/bcsd/proxy/8787/status`
+
+export default ({ children }) => <Section name='Running Prefect Flows'>{children}</Section>
diff --git a/docs/public/dummy.txt b/docs/public/dummy.txt