Documentation #20
Documentation #20
Conversation
Saving to a separate branch in case this fails horribly.
Working on create___() next.
|
@embrown some of these are corrected in my PR, maybe you can wait until mine is approved. |
@embrown @doutriaux1 are there any pieces in this PR that could be repurposed to construct documentation across the other code bases CDAT/cdms#13, CDAT/cdutil#1 and CDAT/genutil#2 |
@durack1 cdutil and genutil, no. There is not enough repetition in the existing docstrings. I would have to look at cdms and see if there's any cases where I could use a similar approach. Mainly the documentation I am generating here is for functions like script(), create___() and get___(), because there was a lot of repetition between the respective docstrings, with only a few keywords that needed to be replaced. |
@embrown, just curious do you have a docstring style that you'd be recommending in order to best document python functions across a suite of packages that will attempt to maintain forward compatibility? I've been following a sphinx-style format (the spyder IDE presents this as inline documentation in the GUI), but haven't done much investigation if this is the best format across software and platforms |
@durack1 I haven't done much research in that regard either. I started documenting this stuff knowing next to nothing about Sphinx and RST format and just kind of learned along the way. If I could do it again, I would probably use NumPy or Google-style documentation. Apparently there's a Sphinx extension called Napoleon that allows you to use those styles, and they are much easier to read than all of the :param: and :type: entries that vcs's documentation currently uses. Plus they allow for functions that have multiple return values (not a big deal with VCS, but I'm seeing a lot of functions with multiple returns in GenUtil/CDUtil). |
Interesting, any chance you have good links to the NumPy or Google-style doc formats? |
@embrown great thanks! |
Adds a function and a dictionary in xmldocs.py to populate docstrings for many functions.
Swaps out previous docstrings for the populated docstrings.
Updates all :Example: entries to doctests.