Merge pull request #1475 from DominicWC/new-notebooks

Adds NK notebooks to the documentation
econ-ark · Jul 17, 2024 · da9e5b4 · da9e5b4
2 parents d883e25 + c84b30e
commit da9e5b4
Show file tree

Hide file tree

Showing 85 changed files with 10,687 additions and 4,074 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -49,8 +49,9 @@ jobs:
       - name: Run Sphinx
         run: >
           sphinx-build
-          -M html Documentation HARK-docs
+          -M html . HARK-docs
           -T
+          -c Documentation
           -W
           -j 1
 

diff --git a/Documentation/_static/override-nbsphinx-gallery.css b/Documentation/_static/override-nbsphinx-gallery.css
diff --git a/Documentation/conf.py b/Documentation/conf.py
@@ -1,5 +1,8 @@
 import warnings
 from datetime import date
+import os
+
+dir = os.path.dirname(__file__)
 
 try:
     import numba
@@ -41,11 +44,23 @@
     "sphinx_design",
 ]
 
+
+include_patterns = [
+    "Documentation**",
+    "index.rst",
+]  # Makes sure that only the file we want documented get documented
+with open(os.path.join(dir, "example_notebooks", "Include_list.txt"), "r") as file:
+    include_patterns += file.readlines()
+include_patterns = [
+    i.replace("\n", "") for i in include_patterns
+]  # Adds example notebooks
+
 exclude_patterns = [
-    "_build",
-    "Thumbs.db",
-    ".DS_Store",
-    "NARK",
+    "Documentation/_build",
+    "Documentation/Thumbs.db",
+    "Documentation/.DS_Store",
+    "Documentation/NARK",
+    "Documentation/index_core.rst",  # Prevents sphinx from getting confused
 ]
 
 language = "en"
@@ -64,7 +79,7 @@
 
 # HTML writer configuration
 html_theme = "pydata_sphinx_theme"
-html_static_path = ["_static"]
+html_static_path = []
 html_css_files = [
     "override-nbsphinx-gallery.css",
 ]
@@ -154,3 +169,5 @@
 
 # nbsphinx configuration
 nbsphinx_execute = "never"  # notebooks are executed via ``nb_exec.py``
+
+suppress_warnings = []
diff --git a/Documentation/example_notebooks/ConsPortfolioModel.ipynb b/Documentation/example_notebooks/ConsPortfolioModel.ipynb
diff --git a/Documentation/example_notebooks/GenIncProcessModel.ipynb b/Documentation/example_notebooks/GenIncProcessModel.ipynb
diff --git a/Documentation/example_notebooks/GenIncProcessModel.py b/Documentation/example_notebooks/GenIncProcessModel.py
diff --git a/Documentation/example_notebooks/Gentle-Intro-To-HARK.ipynb b/Documentation/example_notebooks/Gentle-Intro-To-HARK.ipynb
diff --git a/Documentation/example_notebooks/HARK-struct-2.png b/Documentation/example_notebooks/HARK-struct-2.png
diff --git a/Documentation/example_notebooks/HARK-struct-3.png b/Documentation/example_notebooks/HARK-struct-3.png
diff --git a/Documentation/example_notebooks/HARK-struct-4.png b/Documentation/example_notebooks/HARK-struct-4.png
diff --git a/Documentation/example_notebooks/HowWeSolveIndShockConsumerType.ipynb b/Documentation/example_notebooks/HowWeSolveIndShockConsumerType.ipynb
diff --git a/Documentation/example_notebooks/Include_list.txt b/Documentation/example_notebooks/Include_list.txt
@@ -0,0 +1,13 @@
+examples/Gentle-Intro/Gentle-Intro-To-HARK.ipynb
+examples/ConsIndShockModel/PerfForesightConsumerType.ipynb
+examples/ConsIndShockModel/IndShockConsumerType.ipynb
+examples/ConsIndShockModel/KinkedRconsumerType.ipynb
+examples/ConsPortfolioModel/example_ConsPortfolioModel.ipynb
+examples/GenIncProcessModel/GenIncProcessModel.ipynb
+examples/LifecycleModel/LifecycleModel.ipynb
+examples/HowWeSolveIndShockConsumerType/HowWeSolveIndShockConsumerType.ipynb
+examples/Journeys/Journey-PhD.ipynb
+examples/ConsNewKeynesianModel/Transition_Matrix_Example.ipynb
+examples/ConsNewKeynesianModel/Jacobian_Example.ipynb
+examples/ConsNewKeynesianModel/KS-HARK-presentation.ipynb
+examples/ConsNewKeynesianModel/SSJ_example.ipynb
diff --git a/Documentation/example_notebooks/IndShockConsumerType.ipynb b/Documentation/example_notebooks/IndShockConsumerType.ipynb
diff --git a/Documentation/example_notebooks/Journey-PhD.ipynb b/Documentation/example_notebooks/Journey-PhD.ipynb
diff --git a/Documentation/example_notebooks/JourneyPhDparam.py b/Documentation/example_notebooks/JourneyPhDparam.py
diff --git a/Documentation/example_notebooks/KinkedRconsumerType.ipynb b/Documentation/example_notebooks/KinkedRconsumerType.ipynb
diff --git a/Documentation/example_notebooks/LifecycleModel.ipynb b/Documentation/example_notebooks/LifecycleModel.ipynb
diff --git a/Documentation/example_notebooks/PerfForesightConsumerType.ipynb b/Documentation/example_notebooks/PerfForesightConsumerType.ipynb
diff --git a/Documentation/guides/contributing.md b/Documentation/guides/contributing.md
@@ -375,13 +375,43 @@ To test your changes to the documentation locally, you can render as follows:
 
 2. Run `sphinx-build`:
 
-   ```bash
-   sphinx-build -M html Documentation HARK-docs -T -W
-   ```
+  ```bash
+  sphinx-build -M html . HARK-docs -T -c Documentation -W
+  ```
 
 3. View the rendered HTML by opening the
    `./HARK-docs/html/index.html` file.
 
+#### Adding examples to the documentation
+
+HARK's example notebooks are stored in the HARK/examples file.
+Every pull request to HARK automatically reruns every example notebook
+to keep them up to date.
+
+To add a notebook from the examples folder to the documentation, add a link
+to the notebook to the `Documentation/overview/index.rst` file. It should
+the format `../../examples/AAA/BBB.ipynb`. Then add a link to the notebook
+in the `Documentation/example_notebooks/Include_list.txt` file. It should have
+the format `examples/AAA/BBB.ipynb`.
+
+Sphinx requires it's example notebooks to have a title, and headings in order of
+decreasing size. Make sure the notebook you added has those qualities before you push.
+Otherwise sphinx will fail to build.
+
+:::{warning}
+Make sure not to include the HARK-docs folder in your pull request if you're
+testing locally. HARK will automatically build this file when the pull request
+is made. Including the HARK-docs folder may create unexpected conflicts.
+
+If you would like to build the documentation without warnings being treated as errors use the command:
+```bash
+   sphinx-build -M html . HARK-docs -T -c Documentation
+```
+This lets you see every warning without sphinx quitting after the first issue it finds.
+If you're doing this, make sure to delete the HARK-docs folder before running it again.
+Otherwise it won't show the warnings again, and you won't be able to check if they've been fixed.
+:::
+
 ### Testing
 
 `HARK` has a test suite that ensures correct

diff --git a/Documentation/index.rst → Documentation/index_core.rst b/Documentation/index.rst → Documentation/index_core.rst
@@ -5,13 +5,13 @@ Econ-ARK documentation -- HARK
    :maxdepth: 1
    :hidden:
 
-   Guides <guides/index>
-   Overview & Examples <overview/index>
-   Reference <reference/index>
+   Guides <Documentation/guides/index>
+   Overview & Examples <Documentation/overview/index>
+   Reference <Documentation/reference/index>
 
 
 **Useful links**:
-:doc:`Install HARK <guides/installation>` |
+:doc:`Install HARK <Documentation/guides/installation>` |
 `Source Repository <https://github.com/Econ-ARK/HARK>`__ |
 `Issues & Ideas <https://github.com/Econ-ARK/HARK/issues>`__
 
@@ -44,7 +44,7 @@ you might want to look at the `DemARK
 
       +++
 
-      .. button-ref:: guides/quick_start
+      .. button-ref:: Documentation/guides/quick_start
          :ref-type: doc
          :color: info
          :click-parent:
@@ -63,7 +63,7 @@ you might want to look at the `DemARK
 
       +++
 
-      .. button-ref:: overview/index
+      .. button-ref:: Documentation/overview/index
          :ref-type: doc
          :color: info
          :click-parent:
@@ -83,7 +83,7 @@ you might want to look at the `DemARK
 
       +++
 
-      .. button-ref:: reference/index
+      .. button-ref:: Documentation/reference/index
          :ref-type: doc
          :color: info
          :click-parent:
@@ -105,7 +105,7 @@ you might want to look at the `DemARK
 
       +++
 
-      .. button-ref:: guides/contributing
+      .. button-ref:: Documentation/guides/contributing
          :ref-type: doc
          :color: info
          :click-parent:

diff --git a/Documentation/make.bat b/Documentation/make.bat
@@ -6,7 +6,7 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% -c . ..
 set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%

diff --git a/Documentation/overview/index.rst b/Documentation/overview/index.rst
@@ -15,15 +15,19 @@ Overview
    :caption: Examples
    :maxdepth: 1
 
-   ../example_notebooks/Gentle-Intro-To-HARK.ipynb
-   ../example_notebooks/PerfForesightConsumerType.ipynb
-   ../example_notebooks/IndShockConsumerType.ipynb
-   ../example_notebooks/KinkedRconsumerType.ipynb
-   ../example_notebooks/ConsPortfolioModel.ipynb
-   ../example_notebooks/GenIncProcessModel.ipynb
-   ../example_notebooks/LifecycleModel.ipynb
-   ../example_notebooks/HowWeSolveIndShockConsumerType.ipynb
-   ../example_notebooks/Journey-PhD.ipynb
+   ../../examples/Gentle-Intro/Gentle-Intro-To-HARK.ipynb
+   ../../examples/ConsIndShockModel/PerfForesightConsumerType.ipynb
+   ../../examples/ConsIndShockModel/IndShockConsumerType.ipynb
+   ../../examples/ConsIndShockModel/KinkedRconsumerType.ipynb
+   ../../examples/ConsPortfolioModel/example_ConsPortfolioModel.ipynb
+   ../../examples/GenIncProcessModel/GenIncProcessModel.ipynb
+   ../../examples/LifecycleModel/LifecycleModel.ipynb
+   ../../examples/HowWeSolveIndShockConsumerType/HowWeSolveIndShockConsumerType.ipynb
+   ../../examples/Journeys/Journey-PhD.ipynb
+   ../../examples/ConsNewKeynesianModel/Transition_Matrix_Example.ipynb
+   ../../examples/ConsNewKeynesianModel/Jacobian_Example.ipynb
+   ../../examples/ConsNewKeynesianModel/KS-HARK-presentation.ipynb
+   ../../examples/ConsNewKeynesianModel/SSJ_example.ipynb
 
 .. toctree::
    :hidden: