Merge remote-tracking branch 'upstream/master' into map_coordinates

.github/workflows/documentation.yml

@@ -51,6 +51,7 @@ jobs:
         sphinx-build
         -M html Documentation HARK-docs
         -T
+        -W
 
     - name: Set up git for deployment
       run: |

Documentation/CHANGELOG.md

@@ -46,7 +46,7 @@ Release Date: February, 16, 2023
 - Add methods to non stochastically simulate an economy by computing transition matrices. Functions to compute transition matrices and ergodic distribution have been added [#1155](https://github.com/econ-ark/HARK/pull/1155).
 - Fixes a bug that causes `t_age` and `t_cycle` to get out of sync when reading pre-computed mortality. [#1181](https://github.com/econ-ark/HARK/pull/1181)
 - Adds Methods to calculate Heterogenous Agent Jacobian matrices. [#1185](https://github.com/econ-ark/HARK/pull/1185)
-- Enhances `combine_indep_dstns` to work with labeled distributions (`DiscreteDistributionLabeled`). [#1191](htttps://github.com/econ-ark/HARK/pull/1191)
+- Enhances `combine_indep_dstns` to work with labeled distributions (`DiscreteDistributionLabeled`). [#1191](https://github.com/econ-ark/HARK/pull/1191)
 - Updates the `numpy` random generator from `RandomState` to `Generator`. [#1193](https://github.com/econ-ark/HARK/pull/1193)
 - Turns the income and income+return distributions into `DiscreteDistributionLabeled` objects. [#1189](https://github.com/econ-ark/HARK/pull/1189)
 - Creates `UtilityFuncCRRA` which is an object oriented utility function with a coefficient of constant relative risk aversion and includes derivatives and inverses. Also creates `UtilityFuncCobbDouglas`, `UtilityFuncCobbDouglasCRRA`, and `UtilityFuncConstElastSubs`. [#1168](https://github.com/econ-ark/HARK/pull/1168)

Documentation/conf.py

@@ -1,3 +1,17 @@
+import warnings
+
+try:
+    import numba
+except ImportError:
+    pass
+else:
+    warnings.filterwarnings("ignore",
+                            message="numba.generated_jit.*",
+                            category=numba.NumbaDeprecationWarning)
+    warnings.filterwarnings("ignore",
+                            message=".* 'nopython' .*",
+                            category=numba.NumbaDeprecationWarning)
+
 # Project information
 project = "HARK"
 copyright = "2020, Econ-ARK team"
@@ -17,13 +31,14 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "nbsphinx",
-    "recommonmark",
+    "myst_parser",
 ]
 
 exclude_patterns = [
     "_build",
     "Thumbs.db",
     ".DS_Store",
+    "NARK",
 ]
 
 language = "en"
@@ -46,6 +61,8 @@
 # Use Econ-ARK URL to host the website
 html_baseurl = "https://docs.econ-ark.org"
 
+html_favicon = "images/econ-ark-logo.png"
+
 # sphinx.ext.intersphinx configuration
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
@@ -57,5 +74,8 @@
 # sphinx.ext.autosummary configuration
 autosummary_generate = True
 
+# sphinx.ext.napoleon configuration
+napoleon_use_ivar = True  # solves duplicate object description warning
+
 # nbsphinx configuration
 nbsphinx_execute = "never"  # This is currently not working

Documentation/contributing/CONTRIBUTING.md → Documentation/guides/contributing.md

@@ -4,7 +4,7 @@
 - [Contributing Guide](#contributing-guide)
 - [Developer's Certificate of Origin 1.1](#developer-s-certificate-of-origin-1-1)
 
-## [Code of Conduct](./doc/guides/contributing/coc.md)
+## Code of Conduct
 
 The Econ-ARK project has a
 [Code of Conduct](https://github.com/econ-ark/HARK/blob/master/.github/CODE_OF_CONDUCT.md)

Documentation/guides/index.rst

@@ -0,0 +1,15 @@
+Guides
+======
+
+.. toctree::
+   :caption: Usage
+   :maxdepth: 1
+
+   quick_start
+   installation
+
+.. toctree::
+   :caption: Development
+   :maxdepth: 1
+
+   contributing

Documentation/contributing/Installation_instruction.md → Documentation/guides/installation.md

@@ -1,4 +1,4 @@
-# Installing HARK
+# HARK installation guide
 
 HARK is an open source project written in Python. It's compatible with both Python
 2 and 3, and with the Anaconda distributions of python 2 and 3.
@@ -173,7 +173,7 @@ If you want to make changes or contributions (yay!) to HARK, you'll need to have
 
 1.  Navigate to wherever you want to put the repository and type `git clone git@github.com:econ-ark/HARK.git` ([more details here](https://git-scm.com/documentation)). If you get a permission denied error, you may need to setup SSH for GitHub, or you can clone using HTTPS: 'git clone https://github.com/econ-ark/HARK.git'.
 
-2.  Then, create and activate a [virtual environment](<[virtualenv]((https://virtualenv.pypa.io/en/latest/))>).
+2.  Then, create and activate a [virtual environment](https://virtualenv.pypa.io/en/latest/).
 
 Install virtualenv if you need to and then type:
 

Documentation/quick-start.md → Documentation/guides/quick_start.md

@@ -1,4 +1,4 @@
-hark.readthedocs# Quick Start
+# Quick Start Guide
 
 ## Installing HARK
 
@@ -77,39 +77,39 @@ and from there you can open the notebooks and execute them.
 
 We have a set of 30-second [Elevator Spiels](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#capsule-summaries-of-what-the-econ-ark-project-is) describing the project, tailored to people with several different kinds of background.
 
-The most broadly applicable advice is to go to [Econ-ARK](https://econ-ark.org) and click on "Notebooks", and choose [A Gentle Introduction to HARK](https://hark.readthedocs.io/en/latest/search.html?q=%22A+Gentle+Introduction+to+HARK%22&check_keywords=yes&area=default#) which will launch as a [jupyter notebook](https://jupyter.org/).
+The most broadly applicable advice is to go to [Econ-ARK](https://econ-ark.org) and click on "Notebooks", and choose [A Gentle Introduction to HARK](https://hark.readthedocs.io/en/latest/example_notebooks/Gentle-Intro-To-HARK.html) which will launch as a [jupyter notebook](https://jupyter.org/).
 
-#### [For people with a technical/scientific/computing background but little economics background](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-people-with-a-technicalscientificcomputing-background-but-no-economics-background)
+### [For people with a technical/scientific/computing background but little economics background](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-people-with-a-technicalscientificcomputing-background-but-no-economics-background)
 
-- A good starting point is [A Gentle Introduction to HARK](https://hark.readthedocs.io/en/latest/search.html?q=%22A+Gentle+Introduction+to+HARK%22&check_keywords=yes&area=default#) which provides a light economic intuition.
+- A good starting point is [A Gentle Introduction to HARK](https://hark.readthedocs.io/en/latest/example_notebooks/Gentle-Intro-To-HARK.html) which provides a light economic intuition.
 
-#### [For economists who have done some structural modeling](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-done-some-structural-modeling)
+### [For economists who have done some structural modeling](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-done-some-structural-modeling)
 
 - A full replication of the [Iskhakov, Jørgensen, Rust, and Schjerning](https://onlinelibrary.wiley.com/doi/abs/10.3982/QE643) paper for solving the discrete-continuous retirement saving problem
 
   - An informal discussion of the issues involved is [here](https://github.com/econ-ark/DemARK/blob/master/notebooks/DCEGM-Upper-Envelope.ipynb) (part of the [DemARK](https://github.com/econ-ark/DemARK) repo)
 
 - [Structural-Estimates-From-Empirical-MPCs](https://github.com/econ-ark/DemARK/blob/master/notebooks/Structural-Estimates-From-Empirical-MPCs-Fagereng-et-al.ipynb) is an example of the use of the toolkit in a discussion of a well known paper. (Yes, it is easy enough to use that you can estimate a structural model on somebody else's data in the limited time available for writing a discussion)
 
-#### [For economists who have not yet done any structural modeling but might be persuadable to start](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-not-yet-done-any-structural-modeling-but-might-be-persuadable-to-start)
+### [For economists who have not yet done any structural modeling but might be persuadable to start](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-economists-who-have-not-yet-done-any-structural-modeling-but-might-be-persuadable-to-start)
 
-- Start with [A Gentle Introduction to HARK](https://hark.readthedocs.io/en/latest/search.html?q=%22A+Gentle+Introduction+to+HARK%22&check_keywords=yes&area=default#) to get your feet wet
+- Start with [A Gentle Introduction to HARK](https://hark.readthedocs.io/en/latest/example_notebooks/Gentle-Intro-To-HARK.html) to get your feet wet
 
-- A simple indirect inference/simulated method of moments structural estimation along the lines of Gourinchas and Parker's 2002 Econometrica paper or Cagetti's 2003 paper is performed by the [SolvingMicroDSOPs](https://github.com/econ-ark/REMARK/tree/master/REMARKs/SolvingMicroDSOPs) [REMARK](https://github.com/econ-ark/REMARK); this code implements the solution methods described in the corresponding section of [these lecture notes](http://www.econ2.jhu.edu/people/ccarroll/SolvingMicroDSOPs/)
+- A simple indirect inference/simulated method of moments structural estimation along the lines of Gourinchas and Parker's 2002 Econometrica paper or Cagetti's 2003 paper is performed by the [SolvingMicroDSOPs](https://github.com/econ-ark/SolvingMicroDSOPs/) [REMARK](https://github.com/econ-ark/REMARK); this code implements the solution methods described in the corresponding section of [these lecture notes](https://llorracc.github.io/SolvingMicroDSOPs/).
 
-#### [For Other Developers of Software for Computational Economics](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-other-developers-of-software-for-computational-economics)
+### [For Other Developers of Software for Computational Economics](https://github.com/econ-ark/PARK/blob/master/Elevator-Spiels.md#for-other-developers-of-software-for-computational-economics)
 
-- Our workhorse module is [ConsIndShockModel.py](https://github.com/econ-ark/HARK/blob/master/HARK/ConsumptionSaving/ConsIndShockModel.py) which includes the IndShockConsumerType. A short explanation about the Agent Type can be found [here](https://hark.readthedocs.io/en/latest/search.html?q=%22IndShockConsumerType+Documentation%22&check_keywords=yes&area=default#) and an introduction how it is solved [here](https://hark.readthedocs.io/en/latest/search.html?q=%22How+we+solve+a+model+defined+by+the+IndShockConsumerType+class%22&check_keywords=yes&area=default#).
+- Our workhorse module is [ConsIndShockModel.py](https://github.com/econ-ark/HARK/blob/master/HARK/ConsumptionSaving/ConsIndShockModel.py) which includes the IndShockConsumerType. A short explanation about the Agent Type can be found [here](https://hark.readthedocs.io/en/latest/example_notebooks/IndShockConsumerType.html) and an introduction how it is solved [here](https://hark.readthedocs.io/en/latest/example_notebooks/HowWeSolveIndShockConsumerType.html).
 
 ## Making changes to HARK
 
 If you want to make changes or contributions to HARK, you'll need to have access to the source files. Installing HARK via `pip install econ-ark` (at the command line, or inside Spyder) makes it hard to access those files (and it's a bad idea to mess with the original code anyway because you'll likely forget what changes you made). If you are adept at GitHub, you can [fork](https://help.github.com/en/articles/fork-a-repo) the repo. If you are less experienced, you should download a personal copy of HARK again using `git clone` (see above) or the GitHub Desktop app.
 
-#### Clone HARK
+### Clone HARK
 
 Navigate to wherever you want to put the repository and type `git clone git@github.com:econ-ark/HARK.git` ([more details here](https://git-scm.com/documentation)). If you get a permission denied error, you may need to setup SSH for GitHub, or you can clone using HTTPS: `git clone https://github.com/econ-ark/HARK.git`.
 
-#### (Optionally) Create a virtual environment
+### (Optionally) Create a virtual environment
 
 If you are familiar with [virtual environments](https://virtualenv.pypa.io/en/latest/), you can optionally create and activate a virtual environment which will isolate the econ-ark specific tools from the rest of your computer.
 
@@ -131,16 +131,16 @@ econ-ark\\Scripts\\activate.bat
 
 Once the virtualenv is activated, you may see `(econ-ark)` in your command prompt (depending on how your machine is configured)
 
-#### Install requirements
+### Install requirements
 
 Make sure to change to HARK directory, and install HARK's requirements into the virtual environment with `pip install -r requirements.txt`.
 
-#### Test your installation
+### Test your installation
 
 To check that everything has been set up correctly, run HARK's tests with `python -m unittest`.
 
 ## Next steps
 
 To learn more about how to use HARK, check the next sections in this documentation, in particular the jupyter notebooks.
 
-For help making changes to HARK, check out our [contributing guide](contributing/CONTRIBUTING.md).
+For help making changes to HARK, check out our [contributing guide](contributing.md).

Documentation/index.rst

@@ -1,7 +1,18 @@
-Welcome to HARK's documentation!
-================================
+Econ-ARK documentation -- HARK
+===============================
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Overview & Examples <overview/index>
+   Reference <reference/index>
+   Guides <guides/index>
 
-Heterogenous Agents Resources & toolKit (HARK) is a toolkit for the structural modeling of economic choices of optimizing and non-optimizing heterogeneous agents.
+
+Heterogenous Agents Resources & toolKit (HARK)
+is a toolkit for the structural modeling of economic choices
+of optimizing and non-optimizing heterogeneous agents.
 
 HARK is software written in Python.
 This is the documentation for that software.
@@ -12,35 +23,3 @@ or are contributing to the core software.
 If you are a student trying to learn economics concepts,
 you might want to look at the `DemARK
 <https://github.com/econ-ark/DemARK/>`_ project.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Documentation
-
-   introduction
-   quick-start
-   ARKitecture
-   contributing/CONTRIBUTING.md
-   reference/index
-   CHANGELOG
-   license
-
-.. toctree::
-   :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_1_PhD.ipynb
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`