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
Documentation #20
Conversation
Saving to a separate branch in case this fails horribly.
Working on create___() next.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 ','
@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.