Current Sphinx version incompatible with numpydoc

[sbenthall]

I'm trying to build the documentation using Sphinx.

With sphinx-build properly running with Python 3, I've tried make html in the Documentation directory as per the instructions

I get the following error:

~/projects/econ-ark/HARK/Documentation$ make html
sphinx-build -b html -d ../../HARK-docs/doctrees   . ../../HARK-docs/html
Running Sphinx v2.2.0
Inserting /home/sb/projects/econ-ark/HARK

Extension error:
Could not import extension numpydoc (exception: cannot import name 'Directive')
Makefile:63: recipe for target 'html' failed
make: *** [html] Error 2

Looking up this error, it looks like it's the result of incompatibility between the current version of Sphinx (v2.2.0) and the numpydoc extension:
readthedocs/readthedocs.org#4057

The recommended fix from that issue, which is quite old (from May, 2018) is the fix the Sphinx version in requirements.txt to an early version, sphinx==1.6.7

[sbenthall]

Reverting to sphinx=1.6.7 and trying make html gets this new error:

$ make html
sphinx-build -b html -d ../../HARK-docs/doctrees   . ../../HARK-docs/html
Running Sphinx v1.6.7
Inserting /home/sb/projects/econ-ark/HARK
/home/sb/anaconda3/lib/python3.6/site-packages/sphinx/util/compat.py:40: RemovedInSphinx17Warning: sphinx.util.compat.Directive is deprecated and will be removed in Sphinx 1.7, please use docutils' instead.

RemovedInSphinx17Warning)

Extension error:
Could not import extension recommonmark (exception: No module named 'recommonmark')
Makefile:63: recipe for target 'html' failed
make: *** [html] Error 1

[sbenthall]

This is because recommonmark is not included as a dependency in requirements.txt

[sbenthall]

Fixing this requirements issue and rerunning make html results in this error:

$ make html
sphinx-build -b html -d ../../HARK-docs/doctrees   . ../../HARK-docs/html
Running Sphinx v1.6.7
3.6.8 |Anaconda custom (64-bit)| (default, Dec 30 2018, 01:22:34) 
[GCC 7.3.0]
Inserting /home/sb/projects/econ-ark/HARK
/home/sb/anaconda3/lib/python3.6/site-packages/sphinx/util/compat.py:40: RemovedInSphinx17Warning: sphinx.util.compat.Directive is deprecated and will be removed in Sphinx 1.7, please use docutils' instead.
  RemovedInSphinx17Warning)
loading pickled environment... not yet created
/home/sb/projects/econ-ark/HARK/Documentation/notebooks/DCT-Copula-Illustration.rst: WARNING: document not readable. Ignored.
loading intersphinx inventory from https://docs.python.org/objects.inv...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
[autosummary] generating autosummary for: CONTRIBUTING.md, HARKmanual.md, HARKmanual/ContributingToHARK/ContributingToHARK.md, HARKmanual/HARKmanual.md, generated/HARK.BayerLuetticke.Assets.One.FluctuationsOneAssetIOUs.rst, generated/HARK.BayerLuetticke.Assets.One.FluctuationsOneAssetIOUsBond.rst, generated/HARK.BayerLuetticke.Assets.One.SharedFunc.rst, generated/HARK.BayerLuetticke.Assets.One.SharedFunc2.rst, generated/HARK.BayerLuetticke.Assets.One.SteadyStateOneAssetIOUs.rst, generated/HARK.BayerLuetticke.Assets.One.SteadyStateOneAssetIOUsBond.rst, ..., generated/HARK.BayerLuetticke.Assets.Two.SharedFunc3.rst, generated/HARK.BayerLuetticke.Assets.Two.SteadyStateTwoAsset.rst, generated/HARK.BayerLuetticke.Assets.Two.defineSSParametersTwoAsset.rst, generated/HARK.BayerLuetticke.ConsIndShockModel_extension.rst, index.rst, notebooks/Gentle-Intro-To-HARK.ipynb, notebooks/README.rst, packaging.md, readme.md, submodules/README.rst
WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.Assets.One.Luetticke_wrapper': no module named HARK.BayerLuetticke.Assets.One.Luetticke_wrapper
WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.Assets.Two.EX3SS_20_python2.p': no module named HARK.BayerLuetticke.Assets.Two.EX3SS_20_python2.p
WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.Assets.Two.EX3SS_20_python3.p': no module named HARK.BayerLuetticke.Assets.Two.EX3SS_20_python3.p
WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.BayerLuetticke_wrapper': no module named HARK.BayerLuetticke.BayerLuetticke_wrapper
WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.notebooks.DCT': no module named HARK.BayerLuetticke.notebooks.DCT
WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.notebooks.DCT.ipynb': no module named HARK.BayerLuetticke.notebooks.DCT.ipynb
WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.notebooks.OneAsset': no module named HARK.BayerLuetticke.notebooks.OneAsset

Exception occurred:
  File "/home/sb/projects/econ-ark/HARK/HARK/BayerLuetticke/notebooks/TwoAsset.py", line 162, in <module>
    get_ipython().run_line_magic('matplotlib', 'auto')
NameError: name 'get_ipython' is not defined
The full traceback has been saved in /tmp/sphinx-err-p53q6tm1.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
Makefile:63: recipe for target 'html' failed
make: *** [html] Error 1

As this seems to be due to an issue with a specific notebook and its rendering into the docs, and not the dependency incompatibility issues, I'm going to make a separate issue for this.

[llorracc]

Generically, there is no strong reason for any particular notebook to be included either in the docs or in the Travis testing. Our approach has been mostly "if a notebook doesn't cause problems, great, include it; if not, leave it out." So, feel free to leave out BayerLuetticke, if it is causing problems.

…

On Tue, Oct 22, 2019 at 11:06 AM Sebastian Benthall < ***@***.***> wrote: Fixing this requirements issue and rerunning make html results in this error: $ make html sphinx-build -b html -d ../../HARK-docs/doctrees . ../../HARK-docs/html Running Sphinx v1.6.7 3.6.8 |Anaconda custom (64-bit)| (default, Dec 30 2018, 01:22:34) [GCC 7.3.0] Inserting /home/sb/projects/econ-ark/HARK /home/sb/anaconda3/lib/python3.6/site-packages/sphinx/util/compat.py:40: RemovedInSphinx17Warning: sphinx.util.compat.Directive is deprecated and will be removed in Sphinx 1.7, please use docutils' instead. RemovedInSphinx17Warning) loading pickled environment... not yet created /home/sb/projects/econ-ark/HARK/Documentation/notebooks/DCT-Copula-Illustration.rst: WARNING: document not readable. Ignored. loading intersphinx inventory from https://docs.python.org/objects.inv... intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv [autosummary] generating autosummary for: CONTRIBUTING.md, HARKmanual.md, HARKmanual/ContributingToHARK/ContributingToHARK.md, HARKmanual/HARKmanual.md, generated/HARK.BayerLuetticke.Assets.One.FluctuationsOneAssetIOUs.rst, generated/HARK.BayerLuetticke.Assets.One.FluctuationsOneAssetIOUsBond.rst, generated/HARK.BayerLuetticke.Assets.One.SharedFunc.rst, generated/HARK.BayerLuetticke.Assets.One.SharedFunc2.rst, generated/HARK.BayerLuetticke.Assets.One.SteadyStateOneAssetIOUs.rst, generated/HARK.BayerLuetticke.Assets.One.SteadyStateOneAssetIOUsBond.rst, ..., generated/HARK.BayerLuetticke.Assets.Two.SharedFunc3.rst, generated/HARK.BayerLuetticke.Assets.Two.SteadyStateTwoAsset.rst, generated/HARK.BayerLuetticke.Assets.Two.defineSSParametersTwoAsset.rst, generated/HARK.BayerLuetticke.ConsIndShockModel_extension.rst, index.rst, notebooks/Gentle-Intro-To-HARK.ipynb, notebooks/README.rst, packaging.md, readme.md, submodules/README.rst WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.Assets.One.Luetticke_wrapper': no module named HARK.BayerLuetticke.Assets.One.Luetticke_wrapper WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.Assets.Two.EX3SS_20_python2.p': no module named HARK.BayerLuetticke.Assets.Two.EX3SS_20_python2.p WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.Assets.Two.EX3SS_20_python3.p': no module named HARK.BayerLuetticke.Assets.Two.EX3SS_20_python3.p WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.BayerLuetticke_wrapper': no module named HARK.BayerLuetticke.BayerLuetticke_wrapper WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.notebooks.DCT': no module named HARK.BayerLuetticke.notebooks.DCT WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.notebooks.DCT.ipynb': no module named HARK.BayerLuetticke.notebooks.DCT.ipynb WARNING: [autosummary] failed to import 'HARK.BayerLuetticke.notebooks.OneAsset': no module named HARK.BayerLuetticke.notebooks.OneAsset Exception occurred: File "/home/sb/projects/econ-ark/HARK/HARK/BayerLuetticke/notebooks/TwoAsset.py", line 162, in <module> get_ipython().run_line_magic('matplotlib', 'auto') NameError: name 'get_ipython' is not defined The full traceback has been saved in /tmp/sphinx-err-p53q6tm1.log, if you want to report the issue to the developers. Please also report this if it was a user error, so that a better error message can be provided next time. A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks! Makefile:63: recipe for target 'html' failed make: *** [html] Error 1 As this seems to be due to an issue with a specific notebook and its rendering into the docs, and not the dependency incompatibility issues, I'm going to make a separate issue for this. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#406?email_source=notifications&email_token=AAKCK73GFVVQ4HHQRS7M3B3QP4JHZA5CNFSM4JCRRSM2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEB6CU7Y#issuecomment-545008255>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKCK74VGWQBOMWR3AOWZ3LQP4JHZANCNFSM4JCRRSMQ> .

-- - Chris Carroll