Merge branch 'master' into i857

econ-ark · Nov 14, 2024 · b4ec61e · b4ec61e
2 parents 7348331 + 894d53e
commit b4ec61e
Show file tree

Hide file tree

Showing 129 changed files with 15,876 additions and 5,577 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/CHANGELOG.md b/Documentation/CHANGELOG.md
@@ -12,14 +12,22 @@ For more information on HARK, see [our Github organization](https://github.com/e
 
 Release Date: TBD
 
-#### Major Changes
+### Major Changes
 
+- Adds a discretize method to DBlocks and RBlocks (#1460)[https://github.com/econ-ark/HARK/pull/1460]
 - Allows structural equations in model files to be provided in string form [#1427](https://github.com/econ-ark/HARK/pull/1427)
 - Introduces `HARK.parser' module for parsing configuration files into models [#1427](https://github.com/econ-ark/HARK/pull/1427)
+- Allows construction of shocks with arguments based on mathematical expressions [#1464](https://github.com/econ-ark/HARK/pull/1464)
+- YAML configuration file for the normalized consumption and portolio choice [#1465](https://github.com/econ-ark/HARK/pull/1465)
 
 #### Minor Changes
 
 - Fixes bug in `AgentPopulation` that caused discretization of distributions to not work. [1275](https://github.com/econ-ark/HARK/pull/1275)
+- Adds support for distributions, booleans, and callables as parameters in the `Parameters` class. [1387](https://github.com/econ-ark/HARK/pull/1387)
+- Removes a specific way of accounting for ``employment'' in the idiosyncratic-shocks income process. [1473](https://github.com/econ-ark/HARK/pull/1473)
+- Changes the behavior of make_lognormal_RiskyDstn so that the standard deviation represents the standard deviation of log(returns)
+- Adds detailed parameter and latex documentation to most models.
+- Add PermGroFac constructor that explicitly combines idiosyncratic and aggregate sources of growth. [1489](https://github.com/econ-ark/HARK/pull/1489)
 
 ### 0.15.1
 
@@ -58,7 +66,8 @@ This release drops support for Python 3.8 and 3.9, consistent with SPEC 0, and a
 
 #### Minor Changes
 
-- Add option to pass pre-built grid to `LinearFast`. [#1388](https://github.com/econ-ark/HARK/pull/1388)
+
+- Add option to pass pre-built grid to `LinearFast`. [1388](https://github.com/econ-ark/HARK/pull/1388)
 - Moves calculation of stable points out of ConsIndShock solver, into method called by post_solve [#1349](https://github.com/econ-ark/HARK/pull/1349)
 - Adds cubic spline interpolation and value function construction to "warm glow bequest" models.
 - Fixes cubic spline interpolation for ConsMedShockModel.

diff --git a/Documentation/Style.tex.txt b/Documentation/Style.tex.txt
@@ -0,0 +1 @@
+HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/tex4ht HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-make4ht.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-multibib.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-onlyinsubfile.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-titlepage.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark.cls HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/llorracc-handouts.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/pdfsuppressruntime.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/README.md
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,13 +44,32 @@
     "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
 ]
 
+napoleon_custom_sections = [
+    ("Variables associated with the default constuctor", "params_style"),
+    ("Grid Parameters", "params_style"),
+    ("Solving Parameters", "params_style"),
+    ("Simulation Parameters", "params_style"),
+    ("Constructors", "params_style"),
+    ("Attributes", "returns_style"),
+]
 language = "en"
 
 master_doc = "index"
@@ -64,11 +86,8 @@
 
 # HTML writer configuration
 html_theme = "pydata_sphinx_theme"
-html_static_path = ["_static"]
-html_css_files = [
-    "override-nbsphinx-gallery.css",
-]
-
+html_static_path = []
+html_css_files = ["override-nbsphinx-gallery.css"]
 html_theme_options = {
     "use_edit_page_button": True,
     "icon_links": [
@@ -105,7 +124,7 @@
 }
 
 nbsphinx_prolog = r"""
-{% set docname = 'Documentation/' + env.doc2path(env.docname, base=None) %}
+{% set docname = env.doc2path(env.docname, base=None) %}
 
 .. raw:: html
 
@@ -149,8 +168,13 @@
 # sphinx.ext.autosummary configuration
 autosummary_generate = True
 
+# Orders functions by the source order
+autodoc_member_order = "bysource"
+
 # sphinx.ext.napoleon configuration
 napoleon_use_ivar = True  # solves duplicate object description warning
 
 # 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,14 @@
+examples/Gentle-Intro/Gentle-Intro-To-HARK.ipynb
+examples/LifecycleModel/Cycles_tutorial.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
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/tex4ht HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-make4ht.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-multibib.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-onlyinsubfile.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark-titlepage.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark.cls HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/econark.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/llorracc-handouts.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/pdfsuppressruntime.sty HARK/Documentation/NARK/@resources/texlive/texmf-local/tex/latex/README.md