Merge pull request #353 from ericholscher/eh-sphinx-updates

Update docs to work with Read the Docs
econ-ark · Jul 19, 2019 · dbc168c · dbc168c
2 parents 832cb10 + 6b66524
commit dbc168c
Show file tree

Hide file tree

Showing 12 changed files with 67 additions and 33 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,20 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: Documentation/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: 3.7
+  install:
+    - requirements: requirements.txt
diff --git a/DCT-Copula-Illustration.ipynb b/DCT-Copula-Illustration.ipynb
@@ -1399,7 +1399,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# To Do:\n",
+    "## To Do:\n",
     "\n",
     "1. Plot the _difference_ in the _approximation errors_ for adjusters and nonadjusters\n",
     "1. Make color or transparency be determined by the population density from the copula\n",

diff --git a/Documentation/_static/theme_overrides.css b/Documentation/_static/theme_overrides.css
@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 1400px !important;
+}
diff --git a/Documentation/conf.py b/Documentation/conf.py
@@ -6,8 +6,7 @@
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
-# Note that not all possible configuration values are present in this
-# autogenerated file.
+# Note that not all possible configuration values are present in this # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
@@ -18,12 +17,9 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('../ConsumptionSavingModel/'))
-sys.path.insert(0, os.path.abspath('../cstwMPC/'))
-sys.path.insert(0, os.path.abspath('../SolvingMicroDSOPs/'))
-sys.path.insert(0, os.path.abspath('../FashionVictim/'))
+path = os.path.abspath('..')
+sys.path.insert(0, path)
+print(f'Inserting {path}')
 
 
 
@@ -44,8 +40,16 @@
     'sphinx.ext.mathjax',
     'sphinx.ext.autosummary',
     'numpydoc',
+    'nbsphinx',
+    'recommonmark',
 ]
 
+# This is currently not working
+nbsphinx_execute = 'never'
+
+# Extend theme width
+html_css_files = ['theme_overrides.css']
+
 autodoc_default_flags = ['members']  # must add outside ']' bracket
 autosummary_generate = True
 
@@ -127,7 +131,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'classic' # 'alabaster'
+html_theme = 'sphinx_rtd_theme' # 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

diff --git a/Documentation/includeme.rst b/Documentation/includeme.rst
diff --git a/Documentation/index.rst b/Documentation/index.rst
@@ -1,37 +1,38 @@
-.. HARK documentation master file, created by
-   sphinx-quickstart on Sat Jun  4 15:22:52 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to HARK's documentation!
 ================================
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
+   :caption: User Guide
 
-   includeme
+   readme
 
-.. autosummary::
-   :toctree: generated
+.. toctree::
+   :maxdepth: 2
+   :caption: Notebooks
 
-   HARKutilities
-   HARKsimulation
-   HARKparallel
-   HARKinterpolation
-   HARKestimation
-   HARKcore
+   notebooks/Gentle-Intro-To-HARK
+   notebooks/DCT-Copula-Illustration
 
-   ConsIndShockModel
-   ConsPrefShockModel
-   ConsMarkovModel
-   ConsAggShockModel
-   TractableBufferStockModel
+.. toctree::
+   :maxdepth: 2
+   :caption: Python API
 
-   FashionVictimModel
+   Placeholder <https://example.com>
 
+.. autosummary::
+   :toctree: generated
 
+   HARK.core
+   HARK.dcegm
+   HARK.estimation
+   HARK.interpolation
+   HARK.parallel
+   HARK.simulation
+   HARK.utilities
+   HARK.validators
+   HARK.ConsumptionSaving.ConsAggShockModel
+   HARK.FashionVictim.FashionVictimModel
 
 Indices and tables
 ==================

diff --git a/Documentation/instructions.md → Documentation/instructions.txt b/Documentation/instructions.md → Documentation/instructions.txt
diff --git a/Documentation/notebooks/DCT-Copula-Illustration.ipynb b/Documentation/notebooks/DCT-Copula-Illustration.ipynb
@@ -0,0 +1 @@
+../../DCT-Copula-Illustration.ipynb
diff --git a/Documentation/notebooks/Gentle-Intro-To-HARK.ipynb b/Documentation/notebooks/Gentle-Intro-To-HARK.ipynb
@@ -0,0 +1 @@
+../../Examples/Gentle-Intro-To-HARK.ipynb
diff --git a/Documentation/readme.md b/Documentation/readme.md
@@ -0,0 +1 @@
+../README.md
diff --git a/...on/simple-steps-getting-sphinx-working.md → ...n/simple-steps-getting-sphinx-working.txt b/...on/simple-steps-getting-sphinx-working.md → ...n/simple-steps-getting-sphinx-working.txt
@@ -1,3 +1,5 @@
+# Getting sphinx working
+
 Basic steps to get Sphinx running:
 
 1. Download and install Sphinx, numpydoc:

diff --git a/requirements.txt b/requirements.txt
@@ -10,3 +10,5 @@ flake8
 jupyter
 funcsigs
 jupyter
+sphinx-rtd-theme
+nbsphinx