Remaining Jupyter Book documentation warnings

Start with the warnings that name a file and line, such as the docstrings in ogcore/aggregates.py (revenue, around lines 47-57) and ogcore/firm.py, then check the kernel error in content/theory/demographics.md and households.md. Duplicate equation and label warnings are in firms.md, derivations.md and government.md. Done means rebuilding the Jupyter Book with no warnings, which the issue reports as 50 warnings plus repeating .mplstyle warnings. Some items may need maintainer input on the intended labels.

Currently when I build the Jupyter Book documentation for OG-Core (v. 0.7.0), we get the following 50 warnings plus three repeating .mplstyle-type warnings. We need to fix these.

build succeeded, 50 warnings

Summary of warnings

• 2 warnings: "jupyter_client.kernelspec.NoSuchKernel: No such kernel named ogcore-dev": demographics.md, households.md
• 10 warnings: "Unexpected indentation". ogcore.aggregates.revenue:47, ogcore.aggregates.revenue:56, ogcore.elliptical_u_est.estimation:11, ogcore.firm.get_K:12, ogcore.output_plots.plot_aggregates:17, ogcore.output_plots.plot_aggregates:22, ogcore.output_plots.plot_gdp_ratio:17, ogcore.output_tables.dynamic_revenue_decomposition:49, ogcore.output_tables.macro_table:17, ogcore.parameters.Specifications.update_specifications:24
• 6 warnings: "Block quote ends without a blank line; unexpected unindent." ogcore.aggregates.revenue:48, ogcore.aggregates.revenue:57, ogcore.output_plots.plot_aggregates:18, ogcore.output_plots.plot_gdp_ratio:18, ogcore.output_tables.dynamic_revenue_decomposition:51, ogcore.output_tables.macro_table:18
• 2 warnings: "Definition list ends without a blank line; unexpected unindent." ogcore.aggregates.revenue:52, ogcore.output_plots.plot_aggregates:20
• 3 warnings: "Missing matching underline for section title overline." ogcore.elliptical_u_est:1, ogcore.firm:1, ogcore.txfunc:1
• 1 warnings: "Unexpected section title or transition." ogcore.firm.get_K:17
• 1 warnings: "Inline strong start-string without end-string." output_tables.rst:6
• 1 warnings: "Enumerated list ends without a blank line; unexpected unindent." ogcore.output_tables.dynamic_revenue_decomposition:61
• 1 warnings: "Literal block ends without a blank line; unexpected unindent." ogcore.parameters.Specifications.update_specifications:26
• 1 warnings: "toctree directive not expected with external-toc [etoc.toctree]". public_api.rst:11
• 1 warnings: "Explicit markup ends without a blank line; unexpected unindent." ogcore.tax.get_biz_tax:6
• 2 warnings: "missing attribute mentioned in :members: option: module ogcore.txfunc" gen_3Dscatters_hist, plot_txfunc_v_data
• 1 warnings: "missing attribute topshare in object ogcore.utils.Inequality"
• 1 warnings: "Inline interpreted text or phrase reference start-string without end-string." ogcore.utils.get_initial_path:23
• 4 warnings: "Document or section may net begin with a transition". contributor_guide.md, equilibrium.md, households.md:182, market_clearing.md:116
• 2 warnings: "Couldn't find cache key for notebook file [file path and name]". demographics.md, households.md
• 6 warnings: "duplicate label of equation". EqFirmsCESprodfun in firms.md:11 and derivations.md, EqFirmFOC_L in firms.md:41 and derivations.md, EqFirmFOC_K in firms.md:46 and derivations.md, EqFirmsProfit in government.md:21 and firms.md, EqHHBC in households.md:28 and government.md, EqStnrzCESprodfun in stationarization.md:92 and derivations.md
• 1 warnings: "duplicate label glue, other instance" households.md:16 in demographics.md
• 2 warnings: "duplicate label" chap_intro in content/theory/intro.md:2 and content/intro/intro.md, DEP19 in citations.md:3 for keys DeBackerEtAl:2019 and DEP:2019
• 1 warnings: "undefined label" chap_calibr in equilibrium.md:218
• 1 warnings: "equation not found" EqStnrzMarkClrCap in equilibrium.md:370

Terminal warning output

WARNING: /Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/demographics.md
Traceback (most recent call last):
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-dev/lib/python3.9/site-packages/jupyter_cache/executors/utils.py", line 51, in single_nb_execution
    executenb(
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-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/ogcore-dev/lib/python3.9/asyncio/base_events.py", line 642, in run_until_complete
    return future.result()
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-dev/lib/python3.9/contextlib.py", line 175, in __aenter__
    return await self.gen.__anext__()
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-dev/lib/python3.9/site-packages/nbclient/util.py", line 89, in ensure_async
    result = await obj
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-dev/lib/python3.9/site-packages/jupyter_client/utils.py", line 33, in ensure_async
    return await obj
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-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 ogcore-dev
WARNING: /Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/households.md
Traceback (most recent call last):
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-dev/lib/python3.9/site-packages/jupyter_cache/executors/utils.py", line 51, in single_nb_execution
    executenb(
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-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/ogcore-dev/lib/python3.9/asyncio/base_events.py", line 642, in run_until_complete
    return future.result()
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-dev/lib/python3.9/contextlib.py", line 175, in __aenter__
    return await self.gen.__anext__()
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-dev/lib/python3.9/site-packages/nbclient/util.py", line 89, in ensure_async
    result = await obj
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-dev/lib/python3.9/site-packages/jupyter_client/utils.py", line 33, in ensure_async
    return await obj
  File "/Users/richardevans/opt/anaconda3/envs/ogcore-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/ogcore-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/ogcore-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 ogcore-dev
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/aggregates.py:docstring of ogcore.aggregates.revenue:47: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/aggregates.py:docstring of ogcore.aggregates.revenue:48: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/aggregates.py:docstring of ogcore.aggregates.revenue:52: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/aggregates.py:docstring of ogcore.aggregates.revenue:56: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/aggregates.py:docstring of ogcore.aggregates.revenue:57: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/elliptical_u_est.py:docstring of ogcore.elliptical_u_est:1: WARNING: Missing matching underline for section title overline.

------------------------------------------------------------------------
This script takes a Frisch elasticity parameter and then estimates the
parameters of the elliptical utility fuction that correspond to a
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/elliptical_u_est.py:docstring of ogcore.elliptical_u_est.estimation:11: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/firm.py:docstring of ogcore.firm:1: WARNING: Missing matching underline for section title overline.

------------------------------------------------------------------------
Firm functions for firms in the steady state and along the transition
path
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/firm.py:docstring of ogcore.firm.get_K:12: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/firm.py:docstring of ogcore.firm.get_K:17: WARNING: Unexpected section title or transition.

--------------------------------------------------------------------
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_plots.py:docstring of ogcore.output_plots.plot_aggregates:17: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_plots.py:docstring of ogcore.output_plots.plot_aggregates:18: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_plots.py:docstring of ogcore.output_plots.plot_aggregates:20: WARNING: Definition list ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_plots.py:docstring of ogcore.output_plots.plot_aggregates:22: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_plots.py:docstring of ogcore.output_plots.plot_gdp_ratio:17: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_plots.py:docstring of ogcore.output_plots.plot_gdp_ratio:18: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/api/output_tables.rst:6: WARNING: Inline strong start-string without end-string.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_tables.py:docstring of ogcore.output_tables.dynamic_revenue_decomposition:49: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_tables.py:docstring of ogcore.output_tables.dynamic_revenue_decomposition:51: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_tables.py:docstring of ogcore.output_tables.dynamic_revenue_decomposition:61: WARNING: Enumerated list ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_tables.py:docstring of ogcore.output_tables.macro_table:17: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/output_tables.py:docstring of ogcore.output_tables.macro_table:18: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/parameters.py:docstring of ogcore.parameters.Specifications.update_specifications:24: WARNING: Unexpected indentation.
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/parameters.py:docstring of ogcore.parameters.Specifications.update_specifications:26: WARNING: Literal block ends without a blank line; unexpected unindent.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/api/public_api.rst:11: WARNING: toctree directive not expected with external-toc [etoc.toctree]
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/tax.py:docstring of ogcore.tax.get_biz_tax:6: WARNING: Explicit markup ends without a blank line; unexpected unindent.
WARNING: missing attribute mentioned in :members: option: module ogcore.txfunc, attribute gen_3Dscatters_hist
WARNING: missing attribute mentioned in :members: option: module ogcore.txfunc, attribute plot_txfunc_v_data
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/txfunc.py:docstring of ogcore.txfunc:1: WARNING: Missing matching underline for section title overline.

------------------------------------------------------------------------
This script reads in data generated from the Tax Calculator model.
It then estimates tax functions tau_{s,t}(x,y), where
WARNING: missing attribute topshare in object ogcore.utils.Inequality
/Users/richardevans/Documents/Economics/OSE/OG-Core/ogcore/utils.py:docstring of ogcore.utils.get_initial_path:23: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/contributing/contributor_guide.md:0: WARNING: Document or section may not begin with a transition.
WARNING: Couldn't find cache key for notebook file docs/book/content/theory/demographics.md. Outputs will not be inserted.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/equilibrium.md:305: WARNING: Document or section may not begin with a transition.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/firms.md:11: WARNING: duplicate label of equation EqFirmsCESprodfun, other instance in content/theory/derivations
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/firms.md:41: WARNING: duplicate label of equation EqFirmFOC_L, other instance in content/theory/derivations
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/firms.md:46: WARNING: duplicate label of equation EqFirmFOC_K, other instance in content/theory/derivations
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/government.md:21: WARNING: duplicate label of equation EqFirmsProfit, other instance in content/theory/firms
WARNING: Couldn't find cache key for notebook file docs/book/content/theory/households.md. Outputs will not be inserted.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/households.md:28: WARNING: duplicate label of equation EqHHBC, other instance in content/theory/government
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/households.md:182: WARNING: Document or section may not begin with a transition.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/households.md:16: WARNING: duplicate label glue, other instance in /Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/demographics.md
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/intro.md:2: WARNING: duplicate label chap_intro, other instance in /Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/intro/intro.md
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/market_clearing.md:116: WARNING: Document or section may not begin with a transition.
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/stationarization.md:92: WARNING: duplicate label of equation EqStnrzCESprodfun, other instance in content/theory/derivations
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/citations.md:3: WARNING: duplicate label "DEP19" for keys "DeBackerEtAl:2019" and "DEP:2019"
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] content/theory/stationarization                                                    
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/equilibrium.md:218: WARNING: undefined label: chap_calibr
/Users/richardevans/Documents/Economics/OSE/OG-Core/docs/book/content/theory/equilibrium.md:370: WARNING: equation not found: EqStnrzMarkClrCap

OGcorePlots.mplstyle matplotlibrc warnings
In addition, the compilation log output has many "Bad key" and "Duplicate 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 <td id="LC19" class="blob-code blob-code-inner js-file-line">xtick.bottom in file https://github.com/PSLmodels/OG-Core/blob/master/ogcore/OGcorePlots.mplstyle, line 1246 ('        <td id="LC19" class="blob-code blob-code-inner js-file-line">xtick.bottom         : True   # draw ticks on the bottom side</td>')
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

Duplicate key in file 'https://github.com/PSLmodels/OG-Core/blob/master/ogcore/OGcorePlots.mplstyle', line 1380 ('        <li class="mr-3 mr-lg-0"><a href="https://github.com/pricing" data-hydro-click="{&quot;event_type&quot;:&quot;analytics.event&quot;,&quot;payload&quot;:{&quot;category&quot;:&quot;Footer&quot;,&quot;action&quot;:&quot;go to Pricing&quot;,&quot;label&quot;:&quot;text:Pricing&quot;,&quot;originating_url&quot;:&quot;https://github.com/PSLmodels/OG-Core/blob/master/ogcore/OGcorePlots.mplstyle&quot;,&quot;user_id&quot;:null}}" data-hydro-click-hmac="b7792f6655d48bc47f5cb5dfee6820abb3157eb88d93082ed46ab568e392615d">Pricing</a></li>')

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

@jdebacker