Remaining Jupyter Book documentation warnings

[rickecon]

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>')

@jdebacker