pydoc-markdown + google style docstrings

[eode]

Description

Options we had:

• sphinx
  • Reads Google docstrings
  • More fomalized API
  • Very rudimentary (read: mostly not done) markdown output
  • ended up that we'd be mixing Google Docstrings + RST to get the (hopefully) right markdown output
• pydoc-markdown
  • rough
  • less-formalized API
  • No Google docstrings support
  • Ends up we'd be mixing Google Docstrings + Markdown to get Markdown -- not bad.

in the end I used pydoc-markdown:

• Most changes made in google-docstrings.py
• We'll probably find areas our docstrings don't match the format exactly.
• **The modified copy of pydoc-markdown is in-tree under /gendocs in a quilt repository here **
• There is some conformity to pydoc-markdown's style and structure needed, but not too much.
• Basically, Google Docstrings with markdown support.
  • ..and don't use section headers inside your docstrings.
  • ..but formatting, lists, and code blocks for various languages should pass through nicely.
  • formatting defaults to Python.

[codecov]

Codecov Report

Merging #189 into master will increase coverage by 0.02%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #189      +/-   ##
==========================================
+ Coverage   69.06%   69.08%   +0.02%     
==========================================
  Files          10       10              
  Lines        1545     1546       +1     
==========================================
+ Hits         1067     1068       +1     
  Misses        478      478

Impacted Files	Coverage Δ
api/python/t4/packages.py	87.81% <ø> (ø)	⬆️
api/python/t4/api.py	65.42% <ø> (ø)	⬆️
api/python/t4/bucket.py	63.21% <ø> (ø)	⬆️
api/python/t4/__init__.py	100% <100%> (ø)	⬆️

---

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 caa158d...19b77a4. Read the comment docs.

[ResidentMario]

We should open our own fork of pydoc-markdown that's hosted on the quiltdata GitHub organization, and set up instructions telling the user to draw from there.

[eode]

@ResidentMario Ok, see if this works nicely for you.

# from gendocs dir:
# If in your t4 virtualenv, do this:
 ./build.py
# otherwise, do
/path/to/t4/virtualenv/bin/python3 build.py

..note that this (politely) replaces the version of pydocmd that you have installed, if it's not the expected version.

Docs end up in the ./_build/markdown directory.

[eode]

We should open our own fork of pydoc-markdown that's hosted on the quiltdata GitHub organization, and set up instructions telling the user to draw from there.

Done, and changes to accommodate that are done.

[ResidentMario]

There are some minor issues with e.g. the capitalization of things which don't matter. It'd be easiest to merge this PR, then do another PR lightly correcting any docstrings with residual issues.

Can you add api.py to the generated documentation files as well? There are top-level methods in there that are also important to the user.

Can you move the script output target to t4/docs/API Reference/? Not much reason for the indirection of having to move the files yourself really.

[eode]

There are some minor issues with e.g. the capitalization of things which don't matter. It'd be easiest to merge this PR, then do another PR lightly correcting any docstrings with residual issues.

Agreed -- I fixed a few, but those were mainly in ensuring we had the ability to meet our use cases. Overhauling existing docstrings should probably be a separate PR.

Can you add api.py to the generated documentation files as well? There are top-level methods in there that are also important to the user.

Per our discussion, files renamed as follows:

t4: api.md     # read from t4 directly, but includes relevant code from t4.api
t4.Bucket: Bucket.md
t4.Package: Package.md

Can you move the script output target to t4/docs/API Reference/? Not much reason for the indirection of having to move the files yourself really.

Done.

[eode]

Note:
Heading IDs are a bit ugly right now. However, GitBooks has a nice workaround for this using their own flavor of markdown. This is easy to implement/fix to make the heading IDs a lot nicer, but is probably better done in another PR.

E.g., the markdown heading ## Bucket.config(self, config\_url='https://t4.quiltdata.com/config.json') ends up with an HTML ID/anchor of #bucketconfigself-config_urlhttpst4quiltdatacomconfigjson. After the change, the ID would be #Bucket.config.

[ResidentMario]

LGTM