Docs examples

.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: |

.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

README.md

@@ -24,8 +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
 The documentation for `osier` can be viewed [here](https://osier.readthedocs.io/en/latest/). 
 You can also build the docs locally with:

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.

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
+```