Merge pull request #254 from JMGilbert/main

Add DSCIM mkdocs documentation page
ClimateImpactLab · May 30, 2024 · 8c3e7c5 · 8c3e7c5
2 parents 5a72e74 + 416aa5b
commit 8c3e7c5
Show file tree

Hide file tree

Showing 20 changed files with 129 additions and 3 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,25 @@
+name: website
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocstrings[python]
+      - run: mkdocs gh-deploy --force
diff --git a/README.md b/README.md
@@ -54,7 +54,6 @@ serve as the main classes to call different menu options.
 
 ```mermaid
 graph TD
-
 SubGraph1Flow(Storage and I/O)
   subgraph "Storage utilities"
   SubGraph1Flow --> A[Stacked_damages]
@@ -67,7 +66,7 @@ SubGraph1Flow(Storage and I/O)
   B[MainMenu] --> C[AddingUpRecipe];
   B[MainMenu] --> D[RiskAversionRecipe];
   B[MainMenu] --> E[EquityRecipe]
-end
+  end
 ```
 
 `StackedDamages` takes care of parsing all monetized damage data from several

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1 @@
+--8<-- "README.md"
diff --git a/docs/menu/baseline.md b/docs/menu/baseline.md
@@ -0,0 +1 @@
+::: dscim.menu.baseline
diff --git a/docs/menu/decorators.md b/docs/menu/decorators.md
@@ -0,0 +1 @@
+::: dscim.menu.decorators
diff --git a/docs/menu/equity.md b/docs/menu/equity.md
@@ -0,0 +1 @@
+::: dscim.menu.equity
diff --git a/docs/menu/main_recipe.md b/docs/menu/main_recipe.md
@@ -0,0 +1 @@
+::: dscim.menu.main_recipe
diff --git a/docs/menu/risk_aversion.md b/docs/menu/risk_aversion.md
@@ -0,0 +1 @@
+::: dscim.menu.risk_aversion
diff --git a/docs/menu/simple_storage.md b/docs/menu/simple_storage.md
@@ -0,0 +1 @@
+::: dscim.menu.simple_storage
diff --git a/docs/preprocessing/input_damages.md b/docs/preprocessing/input_damages.md
@@ -0,0 +1 @@
+::: dscim.preprocessing.input_damages
diff --git a/docs/preprocessing/midprocessing.md b/docs/preprocessing/midprocessing.md
@@ -0,0 +1 @@
+::: dscim.preprocessing.midprocessing
diff --git a/docs/preprocessing/preprocessing.md b/docs/preprocessing/preprocessing.md
@@ -0,0 +1 @@
+::: dscim.preprocessing.preprocessing
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -0,0 +1,11 @@
+[data-md-color-scheme="CILlight"] {
+  --md-primary-fg-color:        #4DC8D6;
+  --md-primary-fg-color--light: #BAE8E2;
+  --md-primary-fg-color--dark:  #3393B0;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color:        #3393B0;
+  --md-primary-fg-color--light: #BAE8E2;
+  --md-primary-fg-color--dark:  #3393B0;
+}
diff --git a/docs/utils/functions.md b/docs/utils/functions.md
@@ -0,0 +1 @@
+::: dscim.utils.functions
diff --git a/docs/utils/menu_runs.md b/docs/utils/menu_runs.md
@@ -0,0 +1 @@
+::: dscim.utils.menu_runs
diff --git a/docs/utils/rff.md b/docs/utils/rff.md
@@ -0,0 +1 @@
+::: dscim.utils.rff
diff --git a/docs/utils/utils.md b/docs/utils/utils.md
@@ -0,0 +1 @@
+::: dscim.utils.utils
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,68 @@
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+
+site_name: dscim Documentation
+repo_url: "https://github.com/climateimpactlab/dscim"
+
+theme:
+  name: "material"
+
+  palette:
+
+  # Palette toggle for light mode
+  - scheme: CILlight
+    toggle:
+      icon: material/brightness-7 
+      name: Switch to dark mode
+
+  # Palette toggle for dark mode
+  - scheme: slate
+    toggle:
+      icon: material/brightness-4
+      name: Switch to light mode
+
+extra_css:
+  - stylesheets/extra.css
+
+plugins:
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: "numpy"
+            summary: true
+            separate_signature: true
+            show_object_full_path: true
+            show_root_toc_entry: false
+  - search
+
+markdown_extensions:
+  - "pymdownx.snippets"
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+nav:
+  - Home: index.md
+  - API Reference:
+      - dscim.menu:
+        - baseline: menu/baseline.md
+        - main_recipe: menu/main_recipe.md
+        - risk_aversion: menu/risk_aversion.md
+        - equity: menu/equity.md
+        - simple_storage: menu/simple_storage.md
+        - decorators: menu/decorators.md
+      - dscim.preprocessing:
+        - input_damages: preprocessing/input_damages.md
+        - midprocessing: preprocessing/midprocessing.md
+        - preprocessing: preprocessing/preprocessing.md
+      - dscim.utils:
+        - functions: utils/functions.md
+        - menu_runs: utils/menu_runs.md
+        - rff: utils/rff.md
+        - utils: utils/utils.md
+  - Changelog: changelog.md
+
diff --git a/pyproject.toml b/pyproject.toml
@@ -28,9 +28,17 @@ dependencies = [
     "zarr",
 ]
 
+[project.optional-dependencies]
+docs = [
+    "mkdocs",
+    "mkdocstrings[python]",
+    "mkdocs-material",
+]
+
+
 [project.urls]
 Homepage = "https://github.com/ClimateImpactLab/dscim"
-Documentation = "https://github.com/ClimateImpactLab/dscim"
+Documentation = "https://ClimateImpactLab.github.io/dscim"
 Source = "https://github.com/ClimateImpactLab/dscim"
 "Bug Tracker" = "https://github.com/ClimateImpactLab/dscim/issues"