New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation #20

Merged
merged 16 commits into from Oct 5, 2016

Conversation

Projects
None yet
2 participants
@ghost

ghost commented Oct 5, 2016

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

This comment has been minimized.

Member

doutriaux1 commented Oct 5, 2016

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

@doutriaux1 doutriaux1 merged commit 916a69e into master Oct 5, 2016

@durack1

This comment has been minimized.

Member

durack1 commented Oct 6, 2016

@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

This comment has been minimized.

ghost commented Oct 6, 2016

@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

This comment has been minimized.

Member

durack1 commented Oct 7, 2016

@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

This comment has been minimized.

ghost commented Oct 10, 2016

@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

This comment has been minimized.

Member

durack1 commented Oct 19, 2016

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

@ghost

This comment has been minimized.

ghost commented Oct 19, 2016

@durack1

This comment has been minimized.

Member

durack1 commented Oct 19, 2016

@embrown great thanks!

@doutriaux1 doutriaux1 deleted the documentation branch Jun 13, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment