Merge pull request #45 from samgdotson/docs-examples

Docs examples
arfc · Mar 18, 2024 · 976abcc · 976abcc
2 parents 2de6af8 + 0841bff
commit 976abcc
Show file tree

Hide file tree

Showing 14 changed files with 2,831 additions and 57 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+*.ipynb linguist-vendored
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -36,7 +36,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest
+        pip install flake8 pytest pyomo==6.4.1
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
     - name: Install CBC
       run: |

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -4,6 +4,9 @@ build:
   os: "ubuntu-20.04"
   tools:
     python: "3.9"
+  jobs:
+    post_install:
+      - pip install pyomo==6.4.1
 
 sphinx: 
   configuration: docs/source/conf.py
@@ -13,4 +16,4 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - doc
+        - doc
diff --git a/README.md b/README.md
@@ -24,6 +24,17 @@ cd osier
 pip install .
 # to also install the documentation dependencies
 pip install .[doc]
+
+# followed by 
+pip install pyomo==6.4.1
+```
+
+
+```{note}
+Although `pyomo` is a dependency, the current version of `pyomo` (6.7.1, as of 2/29/24) has a bug
+that prints erroneous errors during an `osier` simulation. Therefore, users are recommended to 
+install a specific version of `pyomo` after the main installation of `osier`. There is an open issue [#50](https://github.com/arfc/osier/issues/50) 
+related to this concern.
 ```
 
 ## Documentation

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,6 +33,8 @@
 extensions = [
     "myst_parser",
     "sphinx.ext.napoleon",
+    "sphinx.ext.duration",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
@@ -41,6 +43,7 @@
     "sphinx_design",
     "sphinx.ext.mathjax", 
     "sphinx.ext.coverage",
+    "nbsphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/source/examples/capacity_expansion_tutorial.ipynb b/docs/source/examples/capacity_expansion_tutorial.ipynb
diff --git a/docs/source/examples/dispatch_tutorial.ipynb b/docs/source/examples/dispatch_tutorial.ipynb
diff --git a/docs/source/examples/index.md b/docs/source/examples/index.md
@@ -0,0 +1,14 @@
+# `Osier` Examples
+
+
+This section has examples that guide users from basic usage to more advanced topics.
+
+
+## Guides
+```{toctree}
+:maxdepth: 3
+
+tech_tutorial
+dispatch_tutorial
+capacity_expansion_tutorial
+```