Restructure navigation (#1302)

* Fix Markdown links * Fix Markdown header levels * Fix Markdown footnotes * Switch Markdown parser to MyST * Fix references in toctrees * Fix title underline length * Remove out of date instructions * Ignore Numba deprecation warnings * Fix ConsRiskyContribModel module docstring * Fix section underline lengths in docstrings * Escape inline markup (``*``) * Escape LaTeX macros in docstrings * Add link to Fashion Victim, from before it was removed * Fix mathematical markup in notebooks * Fix bullet points markup * Fix spacing for sections in ConsIndShockModel.py * Ignore the NARK directory * Fix the duplicate object description warning * Enable failing on warnings during documentation rendering in GitHub Actions * Restructure navigation * Add orphan Tools & Models index pages * Fix table of contents
econ-ark · Jul 14, 2023 · 2209109 · 2209109
1 parent fdab7e7
commit 2209109
Show file tree

Hide file tree

Showing 12 changed files with 108 additions and 92 deletions.
diff --git a/Documentation/contributing/CONTRIBUTING.md → Documentation/guides/contributing.md b/Documentation/contributing/CONTRIBUTING.md → Documentation/guides/contributing.md
diff --git a/Documentation/guides/index.rst b/Documentation/guides/index.rst
@@ -0,0 +1,15 @@
+Guides
+======
+
+.. toctree::
+   :caption: Usage
+   :maxdepth: 1
+
+   quick_start
+   installation
+
+.. toctree::
+   :caption: Development
+   :maxdepth: 1
+
+   contributing
diff --git a/.../contributing/Installation_instruction.md → Documentation/guides/installation.md b/.../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.

diff --git a/Documentation/quick-start.md → Documentation/guides/quick_start.md b/Documentation/quick-start.md → Documentation/guides/quick_start.md
@@ -1,4 +1,4 @@
-# Quick Start
+# Quick Start Guide
 
 ## Installing HARK
 
@@ -143,4 +143,4 @@ To check that everything has been set up correctly, run HARK's tests with `pytho
 
 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).
diff --git a/Documentation/index.rst b/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,36 +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
-   contributing/Installation_instruction.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-PhD.ipynb
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/Documentation/ARKitecture.md → Documentation/overview/ARKitecture.md b/Documentation/ARKitecture.md → Documentation/overview/ARKitecture.md
diff --git a/Documentation/overview/index.rst b/Documentation/overview/index.rst
@@ -0,0 +1,30 @@
+Overview
+========
+
+.. toctree::
+   :caption: Introduction to HARK
+   :maxdepth: 1
+
+   introduction
+   ARKitecture
+
+.. toctree::
+   :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
+
+.. toctree::
+   :hidden:
+   :caption: Extras
+
+   ../CHANGELOG
+   ../license
diff --git a/Documentation/introduction.md → Documentation/overview/introduction.md b/Documentation/introduction.md → Documentation/overview/introduction.md
@@ -1,4 +1,4 @@
-# Introduction
+# Introduction to HARK
 
 If you are willing to risk some mild psychological trauma, conjure to mind your first experience of hand-coding a structural economic model. Your clunky effort probably built on legacy code provided by an adviser or colleague -- which itself came from who-knows-what apocryphal sources. Efforts to combine elements from one model with those from another were likely frustrated by the ''Tower of Babel'' problem: Code from one source could not ''speak'' to code from another without your own intermediation as a translator, possibly between two unfamiliar languages and aided only by oracular comments that, at best, made sense only in the context of other (now missing) code.
 

diff --git a/Documentation/reference/ConsumptionSaving/index.rst b/Documentation/reference/ConsumptionSaving/index.rst
@@ -1,20 +1,6 @@
-Consumption Saving
---------------------
+:orphan:
 
-.. toctree::
-   :maxdepth: 3
+Consumption Saving
+==================
 
-   ConsAggShockModel
-   ConsGenIncProcessModel
-   ConsIndShockModel
-   ConsIndShockModelFast
-   ConsLaborModel
-   ConsMarkovModel
-   ConsMedModel
-   ConsPortfolioFrameModel
-   ConsPortfolioModel
-   ConsPrefShochModel
-   ConsRepAgentModel
-   ConsRiskyAssetModel
-   ConsRiskyContribModel
-   TractableBufferStockModel
+See :doc:`../index`.
diff --git a/Documentation/reference/index.rst b/Documentation/reference/index.rst
@@ -1,18 +1,40 @@
-API Documentation
-==================
-
-Tools
---------
+API Reference
+=============
 
 .. toctree::
-   :maxdepth: 3
-
-   tools/index
+   :caption: Tools
+   :maxdepth: 1
 
-Models
---------
+   tools/core
+   tools/dcegm
+   tools/distribution
+   tools/econforgeinterp
+   tools/estimation
+   tools/frame
+   tools/helpers
+   tools/interpolation
+   tools/numba_tools
+   tools/parallel
+   tools/rewards
+   tools/simulation
+   tools/utilities
+   tools/validators
 
 .. toctree::
-   :maxdepth: 3
+   :caption: Models
+   :maxdepth: 1
 
-   ConsumptionSaving/index
+   ConsumptionSaving/ConsAggShockModel
+   ConsumptionSaving/ConsGenIncProcessModel
+   ConsumptionSaving/ConsIndShockModel
+   ConsumptionSaving/ConsIndShockModelFast
+   ConsumptionSaving/ConsLaborModel
+   ConsumptionSaving/ConsMarkovModel
+   ConsumptionSaving/ConsMedModel
+   ConsumptionSaving/ConsPortfolioFrameModel
+   ConsumptionSaving/ConsPortfolioModel
+   ConsumptionSaving/ConsPrefShochModel
+   ConsumptionSaving/ConsRepAgentModel
+   ConsumptionSaving/ConsRiskyAssetModel
+   ConsumptionSaving/ConsRiskyContribModel
+   ConsumptionSaving/TractableBufferStockModel
diff --git a/Documentation/reference/tools/index.rst b/Documentation/reference/tools/index.rst
@@ -1,20 +1,6 @@
-Tools
------
+:orphan:
 
-.. toctree::
-   :maxdepth: 3
+Tools
+=====
 
-   core
-   dcegm
-   distribution
-   econforgeinterp
-   estimation
-   frame
-   helpers
-   interpolation
-   numba_tools
-   parallel
-   rewards
-   simulation
-   utilities
-   validators
+See :doc:`../index`.
diff --git a/README.md b/README.md
@@ -238,11 +238,10 @@ If you are worried or don’t know how to start, you can always reach out to the
 
 **After your first contribution please let us know and we will add you to the Contributors list below!**
 
-To install for development see the [Quickstart Guide](https://github.com/econ-ark/HARK/blob/master/Documentation/quick-start.md).
+To install for development see the [Quickstart Guide](https://docs.econ-ark.org/guides/quick_start.html).
 
-For more information on contributing to HARK please see [CONTRIBUTING.md](https://github.com/econ-ark/HARK/blob/master/Documentation/contributing/CONTRIBUTING.md).
-
-Collaborators follow the [COLLABORATOR_GUIDE](https://github.com/econ-ark/HARK/blob/master/Documentation/contributing/CONTRIBUTING.md#contributing-guide) in maintaining the Econ-ARK project.
+For more information on contributing to HARK please see [the contributing guide](https://docs.econ-ark.org/guides/contributing.html).
+This is the guide that collaborators follow in maintaining the Econ-ARK project.
 
 ## Disclaimer