Resolve all outstanding warnings on rendering documentation (#1301)

* 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
econ-ark · Jul 13, 2023 · 09f1843 · 09f1843
1 parent aff3114
commit 09f1843
Show file tree

Hide file tree

Showing 24 changed files with 127 additions and 586 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -51,6 +51,7 @@ jobs:
         sphinx-build
         -M html Documentation HARK-docs
         -T
+        -W
 
     - name: Set up git for deployment
       run: |

diff --git a/Documentation/ARKitecture.md b/Documentation/ARKitecture.md
diff --git a/Documentation/CHANGELOG.md b/Documentation/CHANGELOG.md
@@ -46,7 +46,7 @@ Release Date: February, 16, 2023
 - Add methods to non stochastically simulate an economy by computing transition matrices. Functions to compute transition matrices and ergodic distribution have been added [#1155](https://github.com/econ-ark/HARK/pull/1155).
 - Fixes a bug that causes `t_age` and `t_cycle` to get out of sync when reading pre-computed mortality. [#1181](https://github.com/econ-ark/HARK/pull/1181)
 - Adds Methods to calculate Heterogenous Agent Jacobian matrices. [#1185](https://github.com/econ-ark/HARK/pull/1185)
-- Enhances `combine_indep_dstns` to work with labeled distributions (`DiscreteDistributionLabeled`). [#1191](htttps://github.com/econ-ark/HARK/pull/1191)
+- Enhances `combine_indep_dstns` to work with labeled distributions (`DiscreteDistributionLabeled`). [#1191](https://github.com/econ-ark/HARK/pull/1191)
 - Updates the `numpy` random generator from `RandomState` to `Generator`. [#1193](https://github.com/econ-ark/HARK/pull/1193)
 - Turns the income and income+return distributions into `DiscreteDistributionLabeled` objects. [#1189](https://github.com/econ-ark/HARK/pull/1189)
 - Creates `UtilityFuncCRRA` which is an object oriented utility function with a coefficient of constant relative risk aversion and includes derivatives and inverses. Also creates `UtilityFuncCobbDouglas`, `UtilityFuncCobbDouglasCRRA`, and `UtilityFuncConstElastSubs`. [#1168](https://github.com/econ-ark/HARK/pull/1168)

diff --git a/Documentation/conf.py b/Documentation/conf.py
@@ -1,3 +1,17 @@
+import warnings
+
+try:
+    import numba
+except ImportError:
+    pass
+else:
+    warnings.filterwarnings("ignore",
+                            message="numba.generated_jit.*",
+                            category=numba.NumbaDeprecationWarning)
+    warnings.filterwarnings("ignore",
+                            message=".* 'nopython' .*",
+                            category=numba.NumbaDeprecationWarning)
+
 # Project information
 project = "HARK"
 copyright = "2020, Econ-ARK team"
@@ -17,13 +31,14 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "nbsphinx",
-    "recommonmark",
+    "myst_parser",
 ]
 
 exclude_patterns = [
     "_build",
     "Thumbs.db",
     ".DS_Store",
+    "NARK",
 ]
 
 language = "en"
@@ -57,5 +72,8 @@
 # sphinx.ext.autosummary configuration
 autosummary_generate = True
 
+# sphinx.ext.napoleon configuration
+napoleon_use_ivar = True  # solves duplicate object description warning
+
 # nbsphinx configuration
 nbsphinx_execute = "never"  # This is currently not working
diff --git a/Documentation/contributing/CONTRIBUTING.md b/Documentation/contributing/CONTRIBUTING.md
@@ -4,7 +4,7 @@
 - [Contributing Guide](#contributing-guide)
 - [Developer's Certificate of Origin 1.1](#developer-s-certificate-of-origin-1-1)
 
-## [Code of Conduct](./doc/guides/contributing/coc.md)
+## Code of Conduct
 
 The Econ-ARK project has a
 [Code of Conduct](https://github.com/econ-ark/HARK/blob/master/.github/CODE_OF_CONDUCT.md)

diff --git a/Documentation/contributing/Installation_instruction.md b/Documentation/contributing/Installation_instruction.md
@@ -173,7 +173,7 @@ If you want to make changes or contributions (yay!) to HARK, you'll need to have
 
 1.  Navigate to wherever you want to put the repository and type `git clone git@github.com: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/))>).
+2.  Then, create and activate a [virtual environment](https://virtualenv.pypa.io/en/latest/).
 
 Install virtualenv if you need to and then type:
 

diff --git a/Documentation/index.rst b/Documentation/index.rst
@@ -21,6 +21,7 @@ you might want to look at the `DemARK
    quick-start
    ARKitecture
    contributing/CONTRIBUTING.md
+   contributing/Installation_instruction.md
    reference/index
    CHANGELOG
    license
@@ -36,7 +37,7 @@ you might want to look at the `DemARK
    example_notebooks/GenIncProcessModel.ipynb
    example_notebooks/LifecycleModel.ipynb
    example_notebooks/HowWeSolveIndShockConsumerType.ipynb
-   example_notebooks/Journey_1_PhD.ipynb
+   example_notebooks/Journey-PhD.ipynb
 
 Indices and tables
 ==================