Remaining Jupyter Book documentation warnings #45
Description
Currently when I build the Jupyter Book documentation for OG-USA (v. 0.7.0), we get the following 18 warnings plus two repeating .mplstyle-type warnings. We need to fix these.
build succeeded, 18 warnings
Summary of warnings
- 3 warnings: "jupyter_client.kernelspec.NoSuchKernel: No such kernel named ogusa-dev":
demographics.md,exogenous_parameters.md,earnings.md - 4 warnings: "Definition list ends without a blank line; unexpected unindent."
ogusa.calibrate.Calibration.read_tax_func_estimate:12,ogusa.demographics.get_mort:20,ogusa.demographics.get_pop_objs:30,ogusa.get_micro_data.get_data:29 - 3 warnings: "Missing matching underline for section title overline."
ogusa.demographics:1,ogusa.get_micro_data:1,ogusa.income:1 - 1 warnings: "Unexpected indentation".
ogusa.demographics.get_pop_objs:32 - 1 warnings: "Block quote ends without a blank line; unexpected unindent."
ogusa.demographics.get_pop_objs:33 - 1 warnings: "toctree directive not expected with external-toc [etoc.toctree]".
public_api.rst:11, - 2 warnings: "Document or section may net begin with a transition".
UBI.md,contributor_guide.md - 3 warnings: "Couldn't find cache key for notebook file [file path and name]".
demographics.md,earnings.md,exogenous_parameters.md
Terminal warning output
WARNING: /Users/richardevans/Documents/Economics/OSE/OG-USA/docs/book/content/calibration/demographics.md
Traceback (most recent call last):
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/basic.py", line 141, in execute
yield self.execute_single(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/basic.py", line 154, in execute_single
result = single_nb_execution(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/utils.py", line 51, in single_nb_execution
executenb(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 1117, in execute
return NotebookClient(nb=nb, resources=resources, km=km, **kwargs).execute()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 78, in wrapped
return just_run(coro(*args, **kwargs))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 57, in just_run
return loop.run_until_complete(coro)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/asyncio/base_events.py", line 642, in run_until_complete
return future.result()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 542, in async_execute
async with self.async_setup_kernel(**kwargs):
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/contextlib.py", line 175, in __aenter__
return await self.gen.__anext__()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 500, in async_setup_kernel
await self.async_start_new_kernel(**kwargs)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 412, in async_start_new_kernel
await ensure_async(self.km.start_kernel(extra_arguments=self.extra_arguments, **kwargs))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 89, in ensure_async
result = await obj
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 331, in _async_start_kernel
kernel_cmd, kw = await ensure_async(self.pre_start_kernel(**kw))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/utils.py", line 33, in ensure_async
return await obj
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 295, in _async_pre_start_kernel
self.kernel_spec,
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 131, in kernel_spec
self._kernel_spec = self.kernel_spec_manager.get_kernel_spec(self.kernel_name)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/kernelspec.py", line 292, in get_kernel_spec
raise NoSuchKernel(kernel_name)
jupyter_client.kernelspec.NoSuchKernel: No such kernel named ogusa-dev
WARNING: /Users/richardevans/Documents/Economics/OSE/OG-USA/docs/book/content/calibration/exogenous_parameters.md
Traceback (most recent call last):
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/basic.py", line 141, in execute
yield self.execute_single(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/basic.py", line 154, in execute_single
result = single_nb_execution(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/utils.py", line 51, in single_nb_execution
executenb(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 1117, in execute
return NotebookClient(nb=nb, resources=resources, km=km, **kwargs).execute()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 78, in wrapped
return just_run(coro(*args, **kwargs))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 57, in just_run
return loop.run_until_complete(coro)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/asyncio/base_events.py", line 642, in run_until_complete
return future.result()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 542, in async_execute
async with self.async_setup_kernel(**kwargs):
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/contextlib.py", line 175, in __aenter__
return await self.gen.__anext__()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 500, in async_setup_kernel
await self.async_start_new_kernel(**kwargs)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 412, in async_start_new_kernel
await ensure_async(self.km.start_kernel(extra_arguments=self.extra_arguments, **kwargs))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 89, in ensure_async
result = await obj
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 331, in _async_start_kernel
kernel_cmd, kw = await ensure_async(self.pre_start_kernel(**kw))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/utils.py", line 33, in ensure_async
return await obj
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 295, in _async_pre_start_kernel
self.kernel_spec,
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 131, in kernel_spec
self._kernel_spec = self.kernel_spec_manager.get_kernel_spec(self.kernel_name)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/kernelspec.py", line 292, in get_kernel_spec
raise NoSuchKernel(kernel_name)
jupyter_client.kernelspec.NoSuchKernel: No such kernel named ogusa-dev
WARNING: /Users/richardevans/Documents/Economics/OSE/OG-USA/docs/book/content/calibration/earnings.md
Traceback (most recent call last):
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/basic.py", line 141, in execute
yield self.execute_single(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/basic.py", line 154, in execute_single
result = single_nb_execution(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_cache/executors/utils.py", line 51, in single_nb_execution
executenb(
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 1117, in execute
return NotebookClient(nb=nb, resources=resources, km=km, **kwargs).execute()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 78, in wrapped
return just_run(coro(*args, **kwargs))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 57, in just_run
return loop.run_until_complete(coro)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/asyncio/base_events.py", line 642, in run_until_complete
return future.result()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 542, in async_execute
async with self.async_setup_kernel(**kwargs):
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/contextlib.py", line 175, in __aenter__
return await self.gen.__anext__()
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 500, in async_setup_kernel
await self.async_start_new_kernel(**kwargs)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/client.py", line 412, in async_start_new_kernel
await ensure_async(self.km.start_kernel(extra_arguments=self.extra_arguments, **kwargs))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/nbclient/util.py", line 89, in ensure_async
result = await obj
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 331, in _async_start_kernel
kernel_cmd, kw = await ensure_async(self.pre_start_kernel(**kw))
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/utils.py", line 33, in ensure_async
return await obj
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 295, in _async_pre_start_kernel
self.kernel_spec,
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/manager.py", line 131, in kernel_spec
self._kernel_spec = self.kernel_spec_manager.get_kernel_spec(self.kernel_name)
File "/Users/richardevans/opt/anaconda3/envs/ogusa-dev/lib/python3.9/site-packages/jupyter_client/kernelspec.py", line 292, in get_kernel_spec
raise NoSuchKernel(kernel_name)
jupyter_client.kernelspec.NoSuchKernel: No such kernel named ogusa-dev
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/calibrate.py:docstring of ogusa.calibrate.Calibration.read_tax_func_estimate:12: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/demographics.py:docstring of ogusa.demographics:1: WARNING: Missing matching underline for section title overline.
------------------------------------------------------------------------
Functions for generating demographic objects necessary for the OG-USA
model
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/demographics.py:docstring of ogusa.demographics.get_mort:20: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/demographics.py:docstring of ogusa.demographics.get_pop_objs:30: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/demographics.py:docstring of ogusa.demographics.get_pop_objs:32: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/demographics.py:docstring of ogusa.demographics.get_pop_objs:33: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/get_micro_data.py:docstring of ogusa.get_micro_data:1: WARNING: Missing matching underline for section title overline.
------------------------------------------------------------------------
This program extracts tax rate and income data from the microsimulation
model (Tax-Calculator).
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/get_micro_data.py:docstring of ogusa.get_micro_data.get_data:29: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-USA/ogusa/income.py:docstring of ogusa.income:1: WARNING: Missing matching underline for section title overline.
-----------------------------------------------------------------
Functions for created the matrix of ability levels, e. This can
only be used for looking at the 25, 50, 70, 80, 90, 99, and 100th
/Users/richardevans/Documents/Economics/OSE/OG-USA/docs/book/content/api/public_api.rst:11: WARNING: toctree directive not expected with external-toc [etoc.toctree]
/Users/richardevans/Documents/Economics/OSE/OG-USA/docs/book/content/calibration/UBI.md:43: WARNING: Document or section may not begin with a transition.
WARNING: Couldn't find cache key for notebook file docs/book/content/calibration/demographics.md. Outputs will not be inserted.
WARNING: Couldn't find cache key for notebook file docs/book/content/calibration/earnings.md. Outputs will not be inserted.
WARNING: Couldn't find cache key for notebook file docs/book/content/calibration/exogenous_parameters.md. Outputs will not be inserted.
/Users/richardevans/Documents/Economics/OSE/OG-USA/docs/book/content/contributing/contributor_guide.md:0: WARNING: Document or section may not begin with a transition.
OGcorePlots.mplstyle matplotlibrc warnings
In addition, the compilation log output has many "Bad key" notes associated with the OGcorePlots.mplstyle file that have the following format. The main suggestion is "You probably need to get an updated matplotlibrc file from https://github.com/matplotlib/matplotlib/blob/v3.4.3/matplotlibrc.template or from the matplotlib source distribution."
Bad key <li><a data-ga-click="Footer, go to about, text in file https://github.com/PSLmodels/OG-Core/blob/master/ogcore/OGcorePlots.mplstyle, line 1384 (' <li><a data-ga-click="Footer, go to about, text:about" href="https://github.com/about">About</a></li>')
You probably need to get an updated matplotlibrc file from
https://github.com/matplotlib/matplotlib/blob/v3.4.3/matplotlibrc.template
or from the matplotlib source distribution
The compilation log output also has many "Missing colon" notes also associated with the OGcorePlots.mplstyle file.
Missing colon in file 'https://github.com/PSLmodels/OG-Core/blob/master/ogcore/OGcorePlots.mplstyle', line 1371 (' </ul>')