Documentation

[ghost]

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.

[doutriaux1]

flake8 --max-line-length=120 --ignore=F999,E121,E123,E126,E226,E24,E704,F405 vcs
vcs/Canvas.py:2256:121: E501 line too long (127 > 120 characters)
vcs/Canvas.py:4775:121: E501 line too long (121 > 120 characters)
vcs/colormap.py:348:121: E501 line too long (128 > 120 characters)
vcs/isofill.py:309:14: E225 missing whitespace around operator
vcs/manageElements.py:84:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:253:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:270:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:618:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:725:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:737:121: E501 line too long (122 > 120 characters)
vcs/manageElements.py:768:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:811:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:855:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:882:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:921:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:947:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:1019:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:1057:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1082:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:1152:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:1195:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1265:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1287:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1303:121: E501 line too long (126 > 120 characters)
vcs/manageElements.py:1322:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:1349:121: E501 line too long (122 > 120 characters)
vcs/manageElements.py:1432:121: E501 line too long (124 > 120 characters)
vcs/manageElements.py:1540:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1578:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1596:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1617:1: E302 expected 2 blank lines, found 1
vcs/manageElements.py:1660:1: E302 expected 2 blank lines, found 1
vcs/meshfill.py:307:121: E501 line too long (121 > 120 characters)
vcs/projection.py:1003:58: W292 no newline at end of file
vcs/xmldocs.py:181:121: E501 line too long (134 > 120 characters)
vcs/xmldocs.py:184:121: E501 line too long (133 > 120 characters)
vcs/xmldocs.py:250:9: E225 missing whitespace around operator
vcs/xmldocs.py:270:35: E231 missing whitespace after ','
vcs/xmldocs.py:270:45: E231 missing whitespace after ','
vcs/xmldocs.py:270:60: E231 missing whitespace after ','
vcs/xmldocs.py:339:31: E225 missing whitespace around operator
vcs/xmldocs.py:354:12: E225 missing whitespace around operator
vcs/xmldocs.py:380:20: E231 missing whitespace after ':'
vcs/xmldocs.py:486:23: E231 missing whitespace after ':'
vcs/xmldocs.py:580:15: E225 missing whitespace around operator
vcs/xmldocs.py:654:11: E225 missing whitespace around operator
vcs/xmldocs.py:716:23: E231 missing whitespace after ','

[doutriaux1]

@embrown some of these are corrected in my PR, maybe you can wait until mine is approved.

[durack1]

@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

[ghost]

@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.

[durack1]

@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

[ghost]

@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).

[durack1]

Interesting, any chance you have good links to the NumPy or Google-style doc formats?

[ghost]

@durack1 Google vs. NumPy

[durack1]

@embrown great thanks!