Merge pull request #1436 from DominicWC/master

Basic fixes to the documentation

Documentation/conf.py

@@ -98,8 +98,29 @@
             "attributes": {"target": "_blank"},
         },
     ],
+    "secondary_sidebar_items": {
+        "**": ["page-toc", "sourcelink"],
+        "index": ["page-toc"],
+    },
 }
 
+nbsphinx_prolog = r"""
+{% set docname = 'Documentation/' + env.doc2path(env.docname, base=None) %}
+
+.. raw:: html
+
+    <div class="admonition note">
+      This page was generated from
+      <a class="reference external" href="https://github.com/econ-ark/HARK/tree/master/{{ docname|e }}">{{ docname|e }}</a>.
+      <br />
+      Interactive online version:
+      <span style="white-space: nowrap;"><a href="https://mybinder.org/v2/gh/econ-ark/HARK/master?filepath={{ docname|e }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>.</span>
+      <a href="{{ env.docname.split('/')|last|e + '.ipynb' }}" class="reference download internal" download>Download notebook</a>.
+    </div>
+"""
+myst_enable_extensions = [
+    "colon_fence",
+]
 # Point to Econ-ARK repo for edit buttons
 html_context = {
     "github_url": "https://github.com",

Documentation/guides/installation.md

@@ -1,13 +1,12 @@
 # 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.
+HARK is an open source project written in Python. It's supported for Python versions 3.10 and up.
 
 ## Instructions for a new user
 
-In order to use HARK, you firstly need to download Python and add Python to the PATH. We recommend to install python 3, as eventually support for python 2 will end. If you are not confident about the installation process you can use this step-by-step guide https://realpython.com/installing-python/ .
+In order to use HARK, you firstly need to download Python and add Python to the PATH. If you are not confident about the installation process you can use [this step-by-step guide](https://realpython.com/installing-python/).
 
-Next, install a text editor for Python. If you do not use the Anaconda Python distribution (see below), we recommend [Atom](https://atom.io/). To use Atom for Python, first install it (you can use this [manual](https://flight-manual.atom.io/getting-started/sections/installing-atom/)). Next, install the [packages](https://flight-manual.atom.io/using-atom/sections/atom-packages/) for Python, we recommend to install at least [autocomplete-python](https://atom.io/packages/autocomplete-python) and [atom-ide-debugger-python](https://flight-manual.atom.io/using-atom/sections/atom-packages/). The last enables debugging the Python scripts, that is to set breakpoints and call variables in certain spot of your code (with increase in your codes' sophistication you will find this tools very helpful in finding bugs).
+Next, you'll want a text editor for Python. If you do not use the Anaconda Python distribution (see below), we recommend [VSCode](https://code.visualstudio.com/) or [PyCharm](https://www.jetbrains.com/pycharm/).
 
 After installing Python and the text editor, you can install HARK package. The simplest way is to use [pip](https://pip.pypa.io/en/stable/installing/).
 
@@ -44,9 +43,9 @@ Next, install `econ-ark` into your new virtual environment via pip:
 pip install econ-ark
 ```
 
----
 
-**!NOTE**
+
+:::{note}
 
 If you install econ-ark into the virtual environment, your HARK scripts will not compile unless it is activated.
 
@@ -71,22 +70,21 @@ cd [directory where you located your script]
 python YourScript.py
 ```
 
-For using the text editor, you also need to configure the environment. If you use [Atom](https://atom.io/), simply type `atom` at a command prompt after activating the environment. Atom text editor will open and you will be able to compile your codes which use HARK.
-
+For using the text editor, you also need to configure the environment.
+:::
 ---
 
 ### Using HARK with Anaconda
 
 Installing HARK with pip does not give you full access to HARK's many graphical capabilities. One way to access these capabilities is by using [Anaconda](https://anaconda.com/why-anaconda), which is a distribution of python along with many packages that are frequently used in scientific computing.
 
-1. Download Anaconda for your operating system and follow the installation instructions [at Anaconda.com](https://www.anaconda.com/distribution/#download-section).
+1. Download Anaconda for your operating system and follow the installation instructions [at Anaconda.com](https://www.anaconda.com/download/success).
 
 ---
+:::{note}
 
-**!NOTE**
-
-You can have the default python distribution from python.org and from anaconda, as they do not interfere. However, be careful with setting the PATH. To avoid problems you can eg. set the environment variables path to the default distribution and access anaconda distribution via anaconda prompt.
-
+You can have the default python distribution from python.org and from anaconda, as they do not interfere. However, be careful with setting the PATH. To avoid problems you can set the environment variables path to the default distribution and access anaconda distribution via anaconda prompt.
+:::
 ---
 
 2. Anaconda includes its own virtual environment system called `conda` which stores environments in a preset location (so you don't have to choose). So in order to create and activate an econ-ark virtual environment:
@@ -201,8 +199,7 @@ pip install -e .
 
 ---
 
-**!NOTE**
-
+:::{note}
 To check the package performance with your local changes, use the same command from the command line (after navigating to your HARK directory):
 
 ```
@@ -215,3 +212,4 @@ If for some reason you want to switch back to the PyPI version:
 pip uninstall econ-ark
 pip install econ-ark (options)
 ```
+:::

Documentation/guides/quick_start.md

@@ -2,9 +2,9 @@
 
 ## Installing HARK
 
-HARK is an open source project that is compatible with Python 3. Currently, we recommend using version 3.10 or lower.
+HARK is an open source project that is compatible with Python 3. Currently, we recommend using version 3.10 or higher.
 
-The simplest way to install HARK is to use [pip](https://pip.pypa.io/en/stable/installation/).
+The simplest way to install HARK is to use [pip](https://pip.pypa.io/en/stable/installation/) by running `pip install econ-ark` in your command line.
 
 Before installing HARK, we recommend creating a new virtual environment, which isolates the installation of `econ-ark` from the installations of any other Python tools and packages, thus avoiding conflicts.
 
@@ -18,31 +18,53 @@ pip install econ-ark
 
 ## Learning HARK
 
-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.
+We've prepared a set of 30-second Elevator Spiels 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://docs.econ-ark.org/example_notebooks/Gentle-Intro-To-HARK.html) which will launch as a [jupyter notebook](https://jupyter.org/).
+To start learning HARK we recommend working through the [Overview and Examples](https://docs.econ-ark.org/overview/index.html) section starting with [A Gentle Introduction to HARK](https://docs.econ-ark.org/example_notebooks/Gentle-Intro-To-HARK.html).
 
-### [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)
+:::{dropdown} For people without a technical/scientific/computing background
+:color: secondary
+:icon: info
+Recent years have seen major advances in the ability of computational tools to explain the economic behavior of households, firms, and whole economies. But a major impediment to the widespread adoption of these techniques among economists has been the extent to which the advances are the culmination of years of development of intricate and hand-crafted (but mutually incomprehensible) computational tools by a few pioneering scholars and their students. The aim of the Econ-ARK project is to make it much easier for new scholars to begin using these techniques, by providing a modern, robust, open-source set of high-quality computational tools with components that can be mixed, matched, and extended to address the wide variety of problems across all fields of economics that can be effectively studied using such tools.
+:::
 
-- A good starting point is [A Gentle Introduction to HARK](https://docs.econ-ark.org/example_notebooks/Gentle-Intro-To-HARK.html) which provides a light economic intuition.
+:::{dropdown} For people with a technical/scientific/computing background but little economics background
+:color: secondary
+:icon: info
 
-### [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)
+Most of what economists have done so far with 'big data' has been like what Kepler did with astronomical data: Organizing the data, and finding patterns and regularities and interconnections. An alternative approach called 'structural modeling' aims to do, for economic data, what Newton did for astronomical data: Provide a deep and rigorous mathematical (or computational) framework that distills the essence of the underlying behavior that produces the 'big data.' But structural techniques are so novel and computationally difficult that few economists have mastered them. The aim of the Econ-ARK project is to make it much, much easier for new scholars to do structural modeling, by providing a well-documented, open source codebase that contains the core techniques and can be relatively easily adapted to address many different questions.
+:::
 
+:::{dropdown} For economists who have done some structural modeling
+:color: secondary
+:icon: info
+
+The Econ-ARK project is motivated by a sense that quantitative structural modeling of economic agents' behavior (consumers; firms), at present, is roughly like econometric modeling in the 1960s: Lots of theoretical results are available and a great deal can be done in principle, but actually using such tools for any specific research question requires an enormous investment of a scholar's time and attention to learn techniques that are fundamentally not related to economics but instead are algorithmic/computational (in the 1960s, e.g., inverting matrices; now, e.g., solving dynamic stochastic optimization problems). The toolkit is built using the suite of open source, transparent tools for collaborative software development that have become ubiquitous in other fields in the last few years: Github, object-oriented coding, and methods that make it much easier to produce plug-and-play software modules that can be (relatively) easily combined, enhanced and adapted to address new problems.
+
+After working through the [Overview and Examples](https://docs.econ-ark.org/overview/index.html) section:
 - 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)
+:::{dropdown} For economists who have not yet done any structural modeling but might be persuadable to start
+:color: secondary
+:icon: info
 
-- Start with [A Gentle Introduction to HARK](https://docs.econ-ark.org/example_notebooks/Gentle-Intro-To-HARK.html) to get your feet wet
+Dissatisfaction with the ability of Representative Agent models to answer important questions raised by the Great Recession has led to a strong movement in the macroeconomics literature toward 'Heterogeneous Agent' models, in which microeconomic agents (consumers; firms) solve a structural problem calibrated to match microeconomic data; aggregate outcomes are derived by explicitly simulating the equilibrium behavior of populations solving such models. The same kinds of modeling techniques are also gaining popularity among microeconomists, in areas ranging from labor economics to industrial organization. In both macroeconomics and structural micro, the chief barrier to the wide adoption of these techniques has been that programming a structural model has, until now, required a great deal of specialized knowledge and custom software development. The aim of the Econ-ARK project is to provide a robust, well-designed, open-source infrastructure for building such models much more efficiently than has been possible in the past.
 
+After working through the [Overview and Examples](https://docs.econ-ark.org/overview/index.html) section:
 - 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)
+:::{dropdown} For Other Developers of Software for Computational Economics
+:icon: info
+:color: secondary
 
-- 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://docs.econ-ark.org/example_notebooks/IndShockConsumerType.html) and an introduction how it is solved [here](https://docs.econ-ark.org/example_notebooks/HowWeSolveIndShockConsumerType.html).
+The Econ-ARK project's aim is to create a modular and extensible open-source toolkit for solving heterogeneous-agent partial-and general-equilibrium structural models. The code for such models has always been handcrafted, idiosyncratic, poorly documented, and sometimes not generously shared from leading researchers to outsiders. The result that it can take years for a new researcher to become proficient. Building an integrated system from the bottom up using object-oriented programming techniques and other tools (GitHub, open source licensing, unit testing, etc), we aim to provide a platform that will become a focal point for people using such models. At present, the project contains: A set of general purpose tools for solving such models; a number of tutorials and examples of how to use the tools; and complete archives of several papers whose main contribution is structural modeling results, and whose modeling work has been done using the toolkit.
+:::
 
 ### Demonstrations on using HARK
 

Documentation/index.rst

@@ -5,9 +5,9 @@ Econ-ARK documentation -- HARK
    :maxdepth: 1
    :hidden:
 
+   Guides <guides/index>
    Overview & Examples <overview/index>
    Reference <reference/index>
-   Guides <guides/index>
 
 
 **Useful links**:
@@ -56,40 +56,40 @@ you might want to look at the `DemARK
       :padding: 2
       :text-align: center
 
-      **API reference**
-      ^^^^^^^^^^^^^^^^^
+      **Overview and Examples**
+      ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-      The reference guide contains a detailed description of the HARK API,
-      and assumes an understanding of HARK's key concepts.
+      To learn how HARK works and what it's capable of, see the Overview and Examples.
 
       +++
 
-      .. button-ref:: reference/index
+      .. button-ref:: overview/index
          :ref-type: doc
          :color: info
          :click-parent:
          :expand:
 
-         Tools & Models Reference Guide
+         Overview and Examples
 
    .. grid-item-card::
       :padding: 2
       :text-align: center
 
-      **ARKitecture**
-      ^^^^^^^^^^^^^^^
+      **API reference**
+      ^^^^^^^^^^^^^^^^^
 
-      For a high-level overview of Econ-ARK's structure and design, see the ARKitecture.
+      The reference guide contains a detailed description of the HARK API,
+      and assumes an understanding of HARK's key concepts.
 
       +++
 
-      .. button-ref:: overview/ARKitecture
+      .. button-ref:: reference/index
          :ref-type: doc
          :color: info
          :click-parent:
          :expand:
 
-         The ARKitecture
+         Tools & Models Reference Guide
 
    .. grid-item-card::
       :padding: 2

Documentation/overview/ARKitecture.md

@@ -42,7 +42,7 @@ Python modules in HARK can generally be categorized into three types: tools, mod
 
 ## HARK
 
-After you [installed](https://docs.econ-ark.org/guides/quick_start.html) and [cloned the repository of](https://github.com/econ-ark/HARK) HARK, you can explore the content of it. In the subfolder HARK, you can find a range of [general purpose tools](#general-purpose-tools), as well as the next subfolder ConsumptionSaving which has [AgentType Classes](#agenttype-class) and [Market Classes](#market-class).
+After you [installed](https://docs.econ-ark.org/guides/installation.html) and [cloned the repository of](https://github.com/econ-ark/HARK) HARK, you can explore the content of it. In the subfolder HARK, you can find a range of [general purpose tools](#general-purpose-tools), as well as the next subfolder ConsumptionSaving which has [AgentType Classes](#agenttype-class) and [Market Classes](#market-class).
 
 ### General Purpose Tools