Merge pull request #425 from sbenthall/issue-409-intro

Refactor 'readme' in docs into separate files to better use sidebar nav
econ-ark · Nov 7, 2019 · 8dd9790 · 8dd9790
2 parents f5263b9 + 5d0c63f
commit 8dd9790
Show file tree

Hide file tree

Showing 8 changed files with 177 additions and 195 deletions.
diff --git a/Documentation/CONTRIBUTING.md b/Documentation/CONTRIBUTING.md
@@ -1,12 +1,12 @@
 # Contributing to Econ-ARK
 
-### Welcome!
+## Welcome!
 
 Thank you for considering contributing to Econ-ARK!  We're a young project with a small but committed community that's hoping to grow while maintaining our friendly and responsive culture.  Whether you're an economist or a technologist, a writer or a coder, an undergrad or a full professor, a professional or a hobbyist, there's a place for you in the Econ-ARK community. 
 
 We're still creating our contribution infrastructure, so this document is a work in progress.  If you have any questions please feel free to @ or otherwise reach out project manager [Shauna](https://github.com/shaunagm), or lead developers [Chris](https://github.com/llorracc) and [Matt](https://github.com/mnwhite).  If you prefer to connect through email, you can send it to __econ-ark at jhuecon dot org__.
 
-### How to Contribute
+## How to Contribute
 
 We're open to all kinds of contributions, from bug reports to help with our docs to suggestions on how to improve our code.  The best way to figure out if the contribution you'd like to make is something we'd merge or otherwise accept, is to open up an issue in our issue tracker.  Please create an issue rather than immediately submitting pull request, unless the change you'd like to make is so minor you won't mind if the pull request is rejected.  For bigger contributions, we want to proactively talk things through so we don't end up wasting your time.
 
@@ -21,7 +21,7 @@ If you'd like to help with those or any other kind of contribution, reach out to
 
 We don't currently have guidelines for opening issues or pull requests, so include as much information as seems relevant to you, and we'll ask you if we need to know more.
 
-### Responding to Issues & Pull Requests
+## Responding to Issues & Pull Requests
 
 We're trying to get better at managing our open issues and pull requests.  We've created a new set of goals for all issues and pull requests in our Econ-ARK repos:
 
@@ -31,7 +31,7 @@ We're trying to get better at managing our open issues and pull requests.  We've
 
 If you've been waiting on us for more than two weeks for any reason, please feel free to give us a nudge.  Correspondingly, we ask that you respond to any questions or requests from us within two weeks as well, even if it's just to say, "Sorry, I can't get to this for a while yet". If we don't hear back from you, we may close your issue or pull request.  If you want to re-open it, just ask - we're glad to do so.
 
-### Getting Started
+## Getting Started
 
 The [quick start guide](https://github.com/econ-ark/HARK#ii-quick-start-guide) in our README provides instructions for how to get started running HARK.  This also serves as a setup guide for new contributors.  If you run into any problems, please let us know by opening an issue in the issue tracker.
 

diff --git a/Documentation/index.rst b/Documentation/index.rst
@@ -17,7 +17,12 @@ you might want to look at the `DemARK
    :maxdepth: 2
    :caption: User Guide
 
-   readme
+   introduction
+   quick-start
+   list-of-files
+   license
+   warnings-and-behaviors
+   CONTRIBUTING
 
 .. toctree::
    :maxdepth: 2

diff --git a/Documentation/introduction.md b/Documentation/introduction.md
@@ -0,0 +1,13 @@
+# Introduction
+
+This document will tell you how to get HARK up and
+running on your machine, how to get started using it, and give you an
+overview of the main elements of the toolkit.
+
+Other useful resources are:
+
+   * Documentation: [ReadTheDocs](https://hark.readthedocs.io/) 
+   * User guide: [Documentation/HARKmanual.pdf](Documentation/HARKmanual.pdf) 
+      * In the [HARK repository](https://github.com/econ-ark/HARK)
+   * Demonstrations of HARK functionality: [DemARK](https://github.com/econ-ark/DemARK/)
+   * Replications and Explorations Made using the ARK : [REMARK](https://github.com/econ-ark/REMARK/)
diff --git a/Documentation/license.md b/Documentation/license.md
@@ -0,0 +1,5 @@
+# License
+
+All of HARK is licensed under the Apache License, Version 2.0 (ALv2). Please see
+the LICENSE file for the text of the license. More information can be found at:
+http://www.apache.org/dev/apply-license.html
diff --git a/Documentation/readme.md → Documentation/list-of-files.md b/Documentation/readme.md → Documentation/list-of-files.md
@@ -1,181 +1,4 @@
-# Heterogeneous Agents Resources and toolKit (HARK)
-pre-release 0.10.1.dev3
-
-Click the Badge for Citation Info.
-[![DOI](https://zenodo.org/badge/50448254.svg)](https://zenodo.org/badge/latestdoi/50448254)
-
-
-Table of Contents:
-
-* [1.   Introduction](#i-introduction)
-* [2.  Quick start guide](#ii-quick-start-guide)
-    * [Installing](#Installing-HARK)
-    * [Installing Anaconda](#Using-HARK-with-Anaconda)
-    * [Learning HARK](#Learning-HARK)
-* [3. List of files in repository](#iii-list-of-files-in-repository)
-* [4.  Warnings and disclaimers](#iv-warnings-and-disclaimers)
-* [5.   License Information](#v-license)
-
-
-## I. INTRODUCTION
-
-This document will tell you how to get HARK up and
-running on your machine, how to get started using it, and give you an
-overview of the main elements of the toolkit.
-
-Other useful resources are:
-
-   * Documentation: [ReadTheDocs](https://hark.readthedocs.io/) 
-   * User guide: [Documentation/HARKmanual.pdf](Documentation/HARKmanual.pdf) 
-      * In the [HARK repository](https://github.com/econ-ark/HARK)
-   * Demonstrations of HARK functionality: [DemARK](https://github.com/econ-ark/DemARK/)
-   * Replications and Explorations Made using the ARK : [REMARK](https://github.com/econ-ark/REMARK/)
-
-## II. QUICK START GUIDE
-
-### Installing HARK
-
-HARK is an open source project that is compatible with both python 2 and 3. But we recommend
-using python 3; eventually support for python 2 will end.
-
-#### Installing HARK with pip
-
-The simplest way to install HARK is to use [pip](https://pip.pypa.io/en/stable/installing/).
-
-To install HARK with pip, at a command line type `pip install econ-ark`.
-
-(If you want to install a release that is not the default stable release, for instance if you want to install a development release, you'll need to use a "pinned" release number: `pip install econ-ark==0.10.1.dev1`, substituting "0.10.1.dev1" for your desired release number.)
-
-If you are installing via pip, we recommend using a virtual environment such as [virtualenv](https://virtualenv.pypa.io/en/latest/). Creation of a virtual environment isolates the installation of `econ-ark` from the installations of any other python tools and packages.
-
-To install `virtualenv`, then to create an environment named `econ-ark`, and finally to activate that environment:
-
-```
-cd [directory where you want to store the econ-ark virtual environment]
-pip install virtualenv
-virtualenv econ-ark
-source econ-ark/bin/activate
-```
-
-----
-#### Using HARK with Anaconda
-
-If you intend ever to use the toolkit for anything other than running the precooked material we have provided, you should probably install [Anaconda](https://anaconda.com/why-anaconda), which will install 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. 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:
-```
-conda create -n econ-ark anaconda
-conda activate econ-ark
-conda install -c conda-forge econ-ark
-```
-1. Open Spyder, an interactive development environment (IDE) for Python (specifically, iPython).  You may be able to do this through Anaconda's graphical interface, or you can do so from the command line/prompt.  To do so, simply open a command line/prompt and type `spyder`.
-
-1. To verify that spyder has access to HARK try typing `pip install econ-ark` into the iPython shell within Spyder.  If you have successfully installed HARK as above, you should see a lot of messages saying 'Requirement satisfied'.
-
-    * If that doesn't work, you will need to manually add HARK to your Spyder environment.  To do this, you'll need to get the code from Github and import it into Spyder.  To get the code from Github, you can either clone it or download a zipped file.
-
-    * If you have `git` installed on the command line, type `git clone [email protected]:econ-ark/HARK.git` in your chosen directory ([more details here](https://git-scm.com/documentation)).
-
-		* If you do not have `git` available on your computer, you can download the [GitHub Desktop app](https://desktop.github.com/) and use it to make a local clone
-
-    * If you don't want to clone HARK, but just to download it, go to [the HARK repository on GitHub](https://github.com/econ-ark/HARK).  In the upper righthand corner is a button that says "clone or download".  Click the "Download Zip" option and then unzip the contents into your chosen directory.
-
-    Once you've got a copy of HARK in a directory, return to Spyder and navigate to that directory where you put HARK.  This can be done within Spyder by doing `import os` and then using `os.chdir()` to change directories.  `chdir` works just like cd at a command prompt on most operating systems, except that it takes a string as input: `os.chdir('Music')` moves to the Music subdirectory of the current working directory.
-
-6) Most of the modules in HARK are just collections of tools.  There are a few demonstration
-applications that use the tools that you automatically get when you install HARK -- they are listed below in [Application Modules](#application-modules).  A much larger set of uses of HARK can be found at two repositories:
-	* [DemARK](https://github.com/econ-ark/DemARK): Demonstrations of the use of HARK
-	* [REMARK](https://github.com/econ-ark/REMARK): Replications of existing papers made using HARK
-
-You will want to obtain your own local copy of these repos using:
-```
-git clone https://github.com/econ-ark/DemARK.git
-```
-and similarly for the REMARK repo. Once you have downloaded them, you will find that each repo contains a `notebooks` directory that contains a number of [jupyter notebooks](https://jupyter.org/). If you have the jupyter notebook tool installed (it is installed as part of Anaconda), you should be able to launch the
-jupyter notebook app from the command line with the command:
-
-```
-jupyter notebook
-```
-and from there you can open the notebooks and execute them.
-
-#### 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.  
-
-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://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) 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)
-
-* [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb)
-
-##### [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)
-
-* Start with [A Gentle Introduction to HARK](https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb) 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/)
-
-##### [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 is explored and explained (a bit) in [this jupyter notebook](https://github.com/econ-ark/DemARK/blob/master/notebooks/ConsIndShockModel.ipynb)
-
-### Making changes to HARK
-
-If you want to make changes or contributions (yay!) to HARK, you'll need to have access to the source files.  Installing HARK via pip (either 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.
-
-1.  Navigate to wherever you want to put the repository and type `git clone [email protected]: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/))).
-
-For Mac or Linux:
-
-Install virtualenv if you need to and then type:
-
-```
-virtualenv econ-ark
-source econ-ark/bin/activate
-```
-For Windows:
-```
-virtualenv econ-ark
-econ-ark\\Scripts\\activate.bat
-```
-
-3. Once the virtualenv is activated, you may see `(econ-ark)` in your command prompt (depending on how your machine is configured)
-
-3.  Make sure to change to HARK directory, and install HARK's requirements into the virtual environment with `pip install -r requirements.txt`.
-
-4.  To check that everything has been set up correctly, run HARK's tests with `python -m unittest`.
-
-### Trouble with installation?
-
-We've done our best to give correct, thorough instructions on how to install HARK but we know this information may be inaccurate or incomplete.  Please let us know if you run into trouble so we can update this guide!  Here's a list of platforms and versions this guide has been verified for:
-
-| Installation Type | Platform      | Python Version |  Date Tested  |  Tested By |
-| ------------- |:-------------:| -----:| -----:|-----:|
-| basic pip install | Linux (16.04) | 3 | 2019-04-24 | @shaunagm |
-| anaconda | Linux (16.04) | 3 | 2019-04-24 | @shaunagm |
-| basic pip install | MacOS 10.13.2 "High Sierra" | 2.7| 2019-04-26 | @llorracc |
-
-### Next steps
-
-To learn more about how to use HARK, check out our [user manual](Documentation/HARKmanual.pdf).
-
-For help making changes to HARK, check out our [contributing guide](CONTRIBUTING.md).
-
-
-## III. LIST OF FILES IN REPOSITORY
+# List of Files in Repository
 
 This section contains descriptions of the main files in the repo.
 
@@ -390,14 +213,3 @@ Other files that you don't need to worry about:
     * Image for the front cover of the user guide, showing the consumption
     function for the KinkyPref model.
 
-
-## IV. WARNINGS AND DISCLAIMERS
-
-This is a beta version of HARK.  The code has not been extensively tested as it should be.  We hope it is useful, but there are absolutely no guarantees (expressed or implied) that it works or will do what you want.  Use at your own risk.  And please, let us know if you find bugs by posting an issue to [the GitHub page](https://github.com/econ-ark/HARK)!
-
-
-## V. License
-
-All of HARK is licensed under the Apache License, Version 2.0 (ALv2). Please see
-the LICENSE file for the text of the license. More information can be found at:
-http://www.apache.org/dev/apply-license.html