API documentation

[jdebacker]

This PR adds documentation for the Tax-Calculator API to the TC Jupyter Book.

[codecov]

Codecov Report

Merging #2441 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2441   +/-   ##
=======================================
  Coverage   99.92%   99.92%           
=======================================
  Files          13       13           
  Lines        2582     2582           
=======================================
  Hits         2580     2580           
  Misses          2        2           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update be34878...bde0add. Read the comment docs.

[MaxGhenis]

Awesome. Are the .rst files generated?

[jdebacker]

@MaxGhenis The .rst files included in the PR are not auto-generated. As far as I know, that is not possible. But the API documentation in the screen shot is auto-generated from docstrings using those .rst files.

[jdebacker]

@Peter-Metz @MattHJensen Does this look like complete enough API docs that we can include this here (and perhaps remove the old https://taxcalc.readthedocs.io/en/latest/ ?

[hdoupe]

@jdebacker this looks nice! A couple things that I thought about:

• Should methods like adjust, start_year, etc. from the Parameters class be included in the Policy or other classes that inherit from Parameters?
• Type definitions for the public methods could be neat. Although I see that they are specified in the doc-string already and should be probably be added in a separate PR if we want them at all. For example, this is how the Calculator signature would look:

[Peter-Metz]

Hey @jdebacker, this is looking great. I tried building the docs from your fork, but I'm running into this error message:

Exception occurred:
  File "/Users/petermetz/anaconda3/lib/python3.6/site-packages/jupyter_book/toc.py", line 77, in add_toctree
    f"Mixed chapters and individual files in `_toc.yml` entry {parent_name}"
ValueError: Mixed chapters and individual files in `_toc.yml` entry index

I have Jupyter-Book 0.7.2 installed and am running the command jupyter-book build ./docs

Any tips?

[jdebacker]

@Peter-Metz I think this maybe a version issue with Jupyter-Book. I'll update my environment and fix to compile with the latest version (I believe I was using 0.7.1, and there have been changes to the table of contents structure lately).

@hdoupe asks:

Should methods like adjust, start_year, etc. from the Parameters class be included in the Policy or other classes that inherit from Parameters?

I suppose it would be nice to know these methods are available, but I don't know how you pull that into the Sphinx docs when the information is in docstrings in an inherited classes module. Do you know how to make this work?

[hdoupe]

@jdebacker I think you can just add the method names here and jupyter book will pull them off the Policy class. When I did this locally, I lost the link to the source code, but that's probably ok for these methods.

[jdebacker]

@hdoupe Thanks for the note about including methods from the inherited ParamTools.Parameters class - these are now included.

@Peter-Metz I've updated the TOC structure to work with Jupyter-Book 0.7.3. See if things compile for you now. JB is under rapid development, so they had made changes to the TOC structure since I opened this PR using 0.7.1.

[Peter-Metz]

@jdebacker sorry for the delay on this. The API looks great. My only two comments:

• taxcalc.calcfunctions is listed twice in the side bar
• It might be nice to include a page on Tax-Calc's CLI. Jupyter-Book has this nice looking page documenting their CLI

[MattHJensen]

@jdebacker, I expect this will be very helpful to users. Thank you. I just added a WIP tag to the title for the resolution of @Peter-Metz's feedback.

[jdebacker]

@Peter-Metz suggests:

It might be nice to include a page on Tax-Calc's CLI. Jupyter-Book has this nice looking page documenting their CLI

I agree. This is beyond the scope of this PR, however. Here we are only adding docs on the python API. I think there are some existing docs on the CLI, right? If so, those should be brought over to the JupyterBook docs in another PR.

[Peter-Metz]

I think there are some existing docs on the CLI, right? If so, those should be brought over to the JupyterBook docs in another PR.

@jdebacker makes sense to me! It turns out there is extensive documentation on the CLI (which I didn't know existed!). I still think it would be useful to have an API-style reference that lays out all the flags/options. I would be happy to help put this together in a separate PR.

[jdebacker]

@Peter-Metz the taxcalc.calcfunctions documentation is still listed twice in the sidebar. I do not know why and think it maybe some issue with Jupyter-Book:

taxcalc.calcfunctions is listed only once in the _toc.yml file. It is listed only once in the public_api.rst file. When you navigate through the book, it is not listed twice (see screen shot below from the taxcalc.utilsprvt page - taxcalc.calcfunctions is not next in the navigation buttons at the bottom despite what the sidebar says):

We can either hold off on merging until Jupyter-Book fixes whatever issue is causing this behavior or we can be ok with this small bug and merge in this additional documentation for the Python API now. I'd vote for the later because I don't think it's a big deal, but will follow what you think is best.

[Peter-Metz]

We can either hold off on merging until Jupyter-Book fixes whatever issue is causing this behavior or we can be ok with this small bug and merge in this additional documentation for the Python API now. I'd vote for the later because I don't think it's a big deal

@jdebacker agreed, I don't think that should hold this PR up.

cc @MattHJensen I think this PR is good to go

[MattHJensen]

Thanks a lot, @jdebacker, these look great. And thanks for the review @Peter-Metz. Merging.