From dcecaa571b7ee1329224592054f5b8f12c9b3e3b Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 10:08:41 -0700 Subject: [PATCH 1/8] Small updates to get Sphinx working --- Documentation/conf.py | 19 +++++++------- Documentation/includeme.rst | 1 - Documentation/index.rst | 26 ++++++++----------- .../{instructions.md => instructions.txt} | 0 Documentation/readme.md | 1 + ...> simple-steps-getting-sphinx-working.txt} | 2 ++ .../DCT-Copula-Illustration-OneAsset.py | 2 +- 7 files changed, 25 insertions(+), 26 deletions(-) delete mode 100644 Documentation/includeme.rst rename Documentation/{instructions.md => instructions.txt} (100%) create mode 120000 Documentation/readme.md rename Documentation/{simple-steps-getting-sphinx-working.md => simple-steps-getting-sphinx-working.txt} (99%) diff --git a/Documentation/conf.py b/Documentation/conf.py index ec8b22565..7d0a54b25 100644 --- 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,13 @@ 'sphinx.ext.mathjax', 'sphinx.ext.autosummary', 'numpydoc', + 'recommonmark', + # 'autoapi.extension', ] +autoapi_dirs = ['../HARK'] + + autodoc_default_flags = ['members'] # must add outside ']' bracket autosummary_generate = True @@ -127,7 +128,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 deleted file mode 100644 index 2c4ea8f0b..000000000 --- a/Documentation/includeme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../README.txt diff --git a/Documentation/index.rst b/Documentation/index.rst index 543fc3c5e..008f4333b 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -11,25 +11,21 @@ Contents: .. toctree:: :maxdepth: 2 - includeme + readme .. autosummary:: :toctree: generated - HARKutilities - HARKsimulation - HARKparallel - HARKinterpolation - HARKestimation - HARKcore - - ConsIndShockModel - ConsPrefShockModel - ConsMarkovModel - ConsAggShockModel - TractableBufferStockModel - - FashionVictimModel + HARK.core + HARK.dcegm + HARK.estimation + HARK.interpolation + HARK.parallel + HARK.simulation + HARK.utilities + HARK.validators + HARK.ConsumptionSaving.ConsAggShockModel + HARK.FashionVictim.FashionVictimModel diff --git a/Documentation/instructions.md b/Documentation/instructions.txt similarity index 100% rename from Documentation/instructions.md rename to Documentation/instructions.txt diff --git a/Documentation/readme.md b/Documentation/readme.md new file mode 120000 index 000000000..32d46ee88 --- /dev/null +++ b/Documentation/readme.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/Documentation/simple-steps-getting-sphinx-working.md b/Documentation/simple-steps-getting-sphinx-working.txt similarity index 99% rename from Documentation/simple-steps-getting-sphinx-working.md rename to Documentation/simple-steps-getting-sphinx-working.txt index 32efa8ac9..640fd9892 100644 --- a/Documentation/simple-steps-getting-sphinx-working.md +++ b/Documentation/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/HARK/BayerLuetticke/DCT-Copula-Illustration-OneAsset.py b/HARK/BayerLuetticke/DCT-Copula-Illustration-OneAsset.py index 40e6369f2..65ff3a0be 100644 --- a/HARK/BayerLuetticke/DCT-Copula-Illustration-OneAsset.py +++ b/HARK/BayerLuetticke/DCT-Copula-Illustration-OneAsset.py @@ -307,7 +307,7 @@ def StateReduc(self): 'Gamma_control': Gamma_control, 'InvGamma':InvGamma, 'par':self.par, 'mpar':self.mpar, 'aggrshock':aggrshock, 'oc':oc, 'Copula':self.Copula,'grid':self.grid,'targets':self.targets,'P_H':self.P_H, - 'joint_distr': self.joint_distr, 'os':os, 'Output': self.Output}ß + 'joint_distr': self.joint_distr, 'os':os, 'Output': self.Output} From 8c5305a7d14815dbe5f72d0e376ca68e0ee09d59 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 10:10:24 -0700 Subject: [PATCH 2/8] Add config file --- .readthedocs.yml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .readthedocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..93dbcd1b3 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,19 @@ +# .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: [] + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: requirements.txt From b586c985f6680a33868fdd9ebb7c3ced894356b8 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 10:12:14 -0700 Subject: [PATCH 3/8] Add theme to reqs --- requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements.txt b/requirements.txt index 9e16229e5..8cf32af12 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,3 +10,4 @@ flake8 jupyter funcsigs jupyter +sphinx-rtd-theme From 677f76109a7104611b7a8fb75e9b94d6292a2114 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 10:41:25 -0700 Subject: [PATCH 4/8] Some more small changes --- .readthedocs.yml | 3 ++- Documentation/conf.py | 5 +++-- Documentation/index.rst | 23 ++++++++++++++--------- 3 files changed, 19 insertions(+), 12 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 93dbcd1b3..80787b838 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -10,7 +10,8 @@ sphinx: configuration: Documentation/conf.py # Optionally build your docs in additional formats such as PDF and ePub -formats: [] +formats: + - pdf # Optionally set the version of Python and requirements required to build your docs python: diff --git a/Documentation/conf.py b/Documentation/conf.py index 7d0a54b25..d9585506f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -40,11 +40,12 @@ 'sphinx.ext.mathjax', 'sphinx.ext.autosummary', 'numpydoc', + 'nbsphinx', 'recommonmark', - # 'autoapi.extension', ] -autoapi_dirs = ['../HARK'] +# This is currently not working +nbsphinx_execute = 'never' autodoc_default_flags = ['members'] # must add outside ']' bracket diff --git a/Documentation/index.rst b/Documentation/index.rst index 008f4333b..19c2a4b14 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -1,18 +1,25 @@ -.. 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 readme +.. toctree:: + :maxdepth: 2 + :caption: Notebooks + + notebooks/Gentle-Intro-To-HARK + notebooks/DCT-Copula-Illustration + +.. toctree:: + :maxdepth: 2 + :caption: Python API + + Placeholder + .. autosummary:: :toctree: generated @@ -27,8 +34,6 @@ Contents: HARK.ConsumptionSaving.ConsAggShockModel HARK.FashionVictim.FashionVictimModel - - Indices and tables ================== From 021942db51869ff4f5681953369230372e1faa21 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 11:02:29 -0700 Subject: [PATCH 5/8] Add notebooks --- DCT-Copula-Illustration.ipynb | 2 +- Documentation/notebooks/DCT-Copula-Illustration.ipynb | 1 + Documentation/notebooks/Gentle-Intro-To-HARK.ipynb | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) create mode 120000 Documentation/notebooks/DCT-Copula-Illustration.ipynb create mode 120000 Documentation/notebooks/Gentle-Intro-To-HARK.ipynb diff --git a/DCT-Copula-Illustration.ipynb b/DCT-Copula-Illustration.ipynb index 2d9a0e24d..fd20bc26c 100644 --- 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/notebooks/DCT-Copula-Illustration.ipynb b/Documentation/notebooks/DCT-Copula-Illustration.ipynb new file mode 120000 index 000000000..413f61774 --- /dev/null +++ b/Documentation/notebooks/DCT-Copula-Illustration.ipynb @@ -0,0 +1 @@ +../../DCT-Copula-Illustration.ipynb \ No newline at end of file diff --git a/Documentation/notebooks/Gentle-Intro-To-HARK.ipynb b/Documentation/notebooks/Gentle-Intro-To-HARK.ipynb new file mode 120000 index 000000000..f27c3cca7 --- /dev/null +++ b/Documentation/notebooks/Gentle-Intro-To-HARK.ipynb @@ -0,0 +1 @@ +../../Examples/Gentle-Intro-To-HARK.ipynb \ No newline at end of file From 9b6d33b83d4e1d65814d8b9887fccff16ea43816 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 11:05:10 -0700 Subject: [PATCH 6/8] Add nbsphinx req --- Documentation/conf.py | 2 +- requirements.txt | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index d9585506f..be4807867 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -129,7 +129,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' # 'alabaster' +html_theme = 'classic' # '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/requirements.txt b/requirements.txt index 8cf32af12..15583b720 100644 --- a/requirements.txt +++ b/requirements.txt @@ -11,3 +11,4 @@ jupyter funcsigs jupyter sphinx-rtd-theme +nbsphinx From dc5b80d062c8ce881a51b3b3b04aef448b51e35f Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 11:07:16 -0700 Subject: [PATCH 7/8] Use our theme --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index be4807867..d9585506f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -129,7 +129,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 From 057509dd3e766b3d6a44b8b58193d344eabf85b6 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 11 Jul 2019 11:16:45 -0700 Subject: [PATCH 8/8] Extend theme width --- Documentation/_static/theme_overrides.css | 3 +++ Documentation/conf.py | 2 ++ 2 files changed, 5 insertions(+) create mode 100644 Documentation/_static/theme_overrides.css diff --git a/Documentation/_static/theme_overrides.css b/Documentation/_static/theme_overrides.css new file mode 100644 index 000000000..1329f433e --- /dev/null +++ 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 index d9585506f..d026f4f7a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -47,6 +47,8 @@ # 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