search

planetarypy / planetaryimage

Python PDS and Isis Cube file parser.
BSD 3-Clause "New" or "Revised" License
39 stars 20 forks source link

Write docs for PlanetaryImage #70

Closed percurnicus closed 8 years ago

percurnicus commented 8 years ago

Main changes are to the docstrings. Added examples and reformatted cubefile to have numpy docstrings.

godber commented 8 years ago

This fails due to missing imports in docstrings. I hate this problem. It can be fixed at the test suite level by somehow importing matplotlib as plt but then all of our docstrings will not show that bit and people cutting and pasting from the docs will be confused. Or we can go and add the imports to the docstrings. @pbvarga1 the imporant thing to realize is that these docstrings get executed by the travis tests so they need to work. I'd be inclined to just do the imports ... though that is very likely to fail in CI for some reason too.

godber commented 8 years ago

FYI, I think the .. testsetup:: directive is what you can use in sphinx to import something globally (per document) in doctests:

http://www.sphinx-doc.org/en/stable/ext/doctest.html

Though I see you've chosen to comment it out.

godber commented 8 years ago

Now you're being burned by the fact that dictionaries are unordered and in python2 some of your strings are coming back as unicode. Should we just run doctests in py2 or py3 but not both or is there a way to wrap the doctests in a conditional so that some snippets don't run in py2?

percurnicus commented 8 years ago

Ill look into the conditional wrapping or some other solution. I updated the Makefile to test doc strings and will also do so in tox to test py2 compatibility in the docs.