Doctest cleanup (#131)

* Fixes #2, Gfb.rename().
Re-wrote to change ._name and pop old name from elements
if not 'default'. Preserves original objects.

* Working on vcs documentation again.

* Trying to fix doctest strings

* Trying to get testing to work

* Fixing errors for tests

* Working on a script to parse doctest output for error warnings

* Running individual modules through doctest and processing output

* Working on doctest_vcs.py

* Working on doctest scripts

* Working on improving doctest reporting

* Added README.md with links to doctest logs

* Fixed README to be markdown friendly

* Fixed errors in manageElements. Added doctests. General formatting improvements.

* Adding doctests where they are missing.
Fixing doctest errors where applicable.
General documentation formatting fixes.

* Adding doctests/documentation where necessary.
Ran doctests and updated logs.

* Fixing/adding doctests

* Added more examples/doctests to utils.py .
Removed some modules from run_all_doctests.sh .
Fixed xmldocs so it doesn't try to plot projections/templates.
Started dv3d descriptions.

* Tweaked doctest cleanup. Fixed manageElements doctests.

* Organized doctest_info directory.
Minor fixes in Canvas, colormap, and xmldocs.

* Fixed reference to old branch in README.md

* Docstring formatting. Doctest corrections. Changed Not Yet Implemented warning.

* doctest_vcs.py now filters out private functions from the missing
section of the log.

* Fixed more docstring formatting issues.
Make html now reports (almost) no errors.
Re-ran doctests/logging.

* Fixing up template. Deleted old file in scripts/

* Undocumented some internal functions to template.
Added more template documentation.
Working on documentation in various stages for other files.

* Updating logs.

* Fixed taylordiagram examples

* Added example to mtics doc

* Adding doctests to xmldocs:

* Fixed doctests for ticlabels, exts

* Refactored doctest_vcs.py and re-ran tests.

* Working on extracting repetetive params to xmldocs.

* Re-factored xmldocs formatting.
Re-ran doctests and re-reported.

* Added functionality to ignore certain regular expressions when
parsing report output with doctest.py.
Regular expressions can be added via commandline or ignore file.
This will allow us to ignore 'missing' doctests for functions that
don't need documentation, or for aspects of a module/class which
are not functions that errantly get picked up by doctest.testmod.

* Added an Index of VCS functions for the pdf output.
Added docs/API/build_func_index.py to automatically check a list
of modules/classes, get their non-private functions, and write
the RST for linking to those functions in the documentation out
to API/functions/$MODULE_NAME to create the functions index.
Not all functions written out to the /rst files have been
documented.

* Added README.md to doctest_info directories briefly explaining
what's in them and how to use it.
Added an ignore directory to store files for using doctest_vcs.py's --ifile
option.

* Formatted :Example: sections to <=80 lines so they look better
in pdf. Re-ran doctest_vcs.py to check functionality after some
minor edits.

* Removed Makefile call to old function

* Adds doctest_info/ to .gitignore.
Fixes some links.
Adds documentation for dv3d (from documentation site).
changes some xmldocs strings to use .format().

* Added '.. pragma: skip-doctest' statements in some places they are
needed for vcs's test suite.

Updated output for 3d graphics methods to match VCS's output.
These will need to be changed after CDAT/dv3d#14
is resolved.

* Added lots of '.. pragma: skip-doctest' and fixed some broken tests.

* Added skip-doctest to some docstrings.

* Standardized print statements for .list()

* Added things to stop tests from breaking

* Removed some unused files, fixed one context-dependent doctest

.gitignore

@@ -2,6 +2,7 @@
 *.egg-info
 build/
 docs/_build
+docs/doctest_info/
 dist/
 .idea/
 dist/

docs/API/README.md

@@ -0,0 +1,4 @@
+Note:
+-----
+
+Run `build_func_index.py` every once in a while to make sure the VCS function index is being updated

docs/API/build_func_index.py

@@ -0,0 +1,30 @@
+import vcs, inspect
+
+# VCS objects to generate function references for. Some are modules, some are classes.
+# Probably will need to add to this later when there's more documentation
+objects = [vcs.boxfill.Gfb, vcs.Canvas.Canvas, vcs.colormap.Cp, vcs.fillarea.Tf, vcs.isofill.Gfi, vcs.isoline.Gi,
+           vcs.line.Tl, vcs.marker.Tm, vcs.meshfill.Gfm, vcs.projection.Proj, vcs.taylor.Gtd, vcs.template.P,
+           vcs.textcombined.Tc,vcs.textorientation.To, vcs.texttable.Tt, vcs.unified1D.G1d, vcs.vector.Gv,
+           vcs.manageElements, vcs.queries, vcs.utils, vcs.animate_helper, vcs.dv3d, vcs.colors, vcs.displayplot.Dp,
+           vcs.vcshelp, ]
+
+# iterate through objects to find the functions of each, and write RST links for those out to
+# API/functions/$MODULE_NAME.rst
+for obj in objects:
+    if inspect.isclass(obj):
+        key = obj.__module__ + '.' + obj.__name__
+        pred = inspect.ismethod
+    else:
+        key = obj.__name__
+        pred = inspect.isfunction
+    funcs = []
+    tup_l = inspect.getmembers(obj, predicate=pred)
+    for tup in tup_l:
+        if not tup[0][0] == '_':
+            funcs.append(':func:`' + key + '.' + tup[0] + '`\n\n')
+    fname = key.split('.')[1]
+    with open('functions/' + fname + ".rst", "w+") as f:
+        f.write(fname + "\n")
+        map(lambda x: f.write('-'), range(len(fname)))
+        f.write("\n\n")
+        f.writelines(funcs)

docs/API/functions/Canvas.rst

@@ -0,0 +1,307 @@
+Canvas
+------
+
+:func:`vcs.Canvas.Canvas.addfont`
+
+:func:`vcs.Canvas.Canvas.boxfill`
+
+:func:`vcs.Canvas.Canvas.canvasid`
+
+:func:`vcs.Canvas.Canvas.canvasinfo`
+
+:func:`vcs.Canvas.Canvas.cgm`
+
+:func:`vcs.Canvas.Canvas.change_display_graphic_method`
+
+:func:`vcs.Canvas.Canvas.check_name_source`
+
+:func:`vcs.Canvas.Canvas.clean_auto_generated_objects`
+
+:func:`vcs.Canvas.Canvas.clear`
+
+:func:`vcs.Canvas.Canvas.close`
+
+:func:`vcs.Canvas.Canvas.configure`
+
+:func:`vcs.Canvas.Canvas.copyfontto`
+
+:func:`vcs.Canvas.Canvas.create1d`
+
+:func:`vcs.Canvas.Canvas.create3d_dual_scalar`
+
+:func:`vcs.Canvas.Canvas.create3d_scalar`
+
+:func:`vcs.Canvas.Canvas.create3d_vector`
+
+:func:`vcs.Canvas.Canvas.createboxfill`
+
+:func:`vcs.Canvas.Canvas.createcolormap`
+
+:func:`vcs.Canvas.Canvas.createfillarea`
+
+:func:`vcs.Canvas.Canvas.createisofill`
+
+:func:`vcs.Canvas.Canvas.createisoline`
+
+:func:`vcs.Canvas.Canvas.createline`
+
+:func:`vcs.Canvas.Canvas.createmarker`
+
+:func:`vcs.Canvas.Canvas.createmeshfill`
+
+:func:`vcs.Canvas.Canvas.createprojection`
+
+:func:`vcs.Canvas.Canvas.createscatter`
+
+:func:`vcs.Canvas.Canvas.createtaylordiagram`
+
+:func:`vcs.Canvas.Canvas.createtemplate`
+
+:func:`vcs.Canvas.Canvas.createtext`
+
+:func:`vcs.Canvas.Canvas.createtextcombined`
+
+:func:`vcs.Canvas.Canvas.createtextorientation`
+
+:func:`vcs.Canvas.Canvas.createtexttable`
+
+:func:`vcs.Canvas.Canvas.createvector`
+
+:func:`vcs.Canvas.Canvas.createxvsy`
+
+:func:`vcs.Canvas.Canvas.createxyvsy`
+
+:func:`vcs.Canvas.Canvas.createyxvsx`
+
+:func:`vcs.Canvas.Canvas.destroy`
+
+:func:`vcs.Canvas.Canvas.drawfillarea`
+
+:func:`vcs.Canvas.Canvas.drawline`
+
+:func:`vcs.Canvas.Canvas.drawlogooff`
+
+:func:`vcs.Canvas.Canvas.drawlogoon`
+
+:func:`vcs.Canvas.Canvas.drawmarker`
+
+:func:`vcs.Canvas.Canvas.drawtext`
+
+:func:`vcs.Canvas.Canvas.drawtextcombined`
+
+:func:`vcs.Canvas.Canvas.dual_scalar3d`
+
+:func:`vcs.Canvas.Canvas.dummy_user_action`
+
+:func:`vcs.Canvas.Canvas.endconfigure`
+
+:func:`vcs.Canvas.Canvas.eps`
+
+:func:`vcs.Canvas.Canvas.ffmpeg`
+
+:func:`vcs.Canvas.Canvas.fillarea`
+
+:func:`vcs.Canvas.Canvas.flush`
+
+:func:`vcs.Canvas.Canvas.geometry`
+
+:func:`vcs.Canvas.Canvas.get1d`
+
+:func:`vcs.Canvas.Canvas.get3d_dual_scalar`
+
+:func:`vcs.Canvas.Canvas.get3d_scalar`
+
+:func:`vcs.Canvas.Canvas.get3d_vector`
+
+:func:`vcs.Canvas.Canvas.get_selected_display`
+
+:func:`vcs.Canvas.Canvas.getantialiasing`
+
+:func:`vcs.Canvas.Canvas.getboxfill`
+
+:func:`vcs.Canvas.Canvas.getcolorcell`
+
+:func:`vcs.Canvas.Canvas.getcolormap`
+
+:func:`vcs.Canvas.Canvas.getcolormapname`
+
+:func:`vcs.Canvas.Canvas.getcontinentsline`
+
+:func:`vcs.Canvas.Canvas.getcontinentstype`
+
+:func:`vcs.Canvas.Canvas.getdrawlogo`
+
+:func:`vcs.Canvas.Canvas.getfillarea`
+
+:func:`vcs.Canvas.Canvas.getfont`
+
+:func:`vcs.Canvas.Canvas.getfontname`
+
+:func:`vcs.Canvas.Canvas.getfontnumber`
+
+:func:`vcs.Canvas.Canvas.getisofill`
+
+:func:`vcs.Canvas.Canvas.getisoline`
+
+:func:`vcs.Canvas.Canvas.getline`
+
+:func:`vcs.Canvas.Canvas.getmarker`
+
+:func:`vcs.Canvas.Canvas.getmeshfill`
+
+:func:`vcs.Canvas.Canvas.getplot`
+
+:func:`vcs.Canvas.Canvas.getprojection`
+
+:func:`vcs.Canvas.Canvas.getscatter`
+
+:func:`vcs.Canvas.Canvas.gettaylordiagram`
+
+:func:`vcs.Canvas.Canvas.gettemplate`
+
+:func:`vcs.Canvas.Canvas.gettext`
+
+:func:`vcs.Canvas.Canvas.gettextcombined`
+
+:func:`vcs.Canvas.Canvas.gettextextent`
+
+:func:`vcs.Canvas.Canvas.gettextorientation`
+
+:func:`vcs.Canvas.Canvas.gettexttable`
+
+:func:`vcs.Canvas.Canvas.getvector`
+
+:func:`vcs.Canvas.Canvas.getxvsy`
+
+:func:`vcs.Canvas.Canvas.getxyvsy`
+
+:func:`vcs.Canvas.Canvas.getyxvsx`
+
+:func:`vcs.Canvas.Canvas.gif`
+
+:func:`vcs.Canvas.Canvas.grid`
+
+:func:`vcs.Canvas.Canvas.gs`
+
+:func:`vcs.Canvas.Canvas.initLogoDrawing`
+
+:func:`vcs.Canvas.Canvas.interact`
+
+:func:`vcs.Canvas.Canvas.isinfile`
+
+:func:`vcs.Canvas.Canvas.islandscape`
+
+:func:`vcs.Canvas.Canvas.isofill`
+
+:func:`vcs.Canvas.Canvas.isoline`
+
+:func:`vcs.Canvas.Canvas.isopened`
+
+:func:`vcs.Canvas.Canvas.isportrait`
+
+:func:`vcs.Canvas.Canvas.landscape`
+
+:func:`vcs.Canvas.Canvas.line`
+
+:func:`vcs.Canvas.Canvas.listelements`
+
+:func:`vcs.Canvas.Canvas.marker`
+
+:func:`vcs.Canvas.Canvas.match_color`
+
+:func:`vcs.Canvas.Canvas.meshfill`
+
+:func:`vcs.Canvas.Canvas.objecthelp`
+
+:func:`vcs.Canvas.Canvas.onClosing`
+
+:func:`vcs.Canvas.Canvas.open`
+
+:func:`vcs.Canvas.Canvas.orientation`
+
+:func:`vcs.Canvas.Canvas.pdf`
+
+:func:`vcs.Canvas.Canvas.plot`
+
+:func:`vcs.Canvas.Canvas.plot_annotation`
+
+:func:`vcs.Canvas.Canvas.plot_filledcontinents`
+
+:func:`vcs.Canvas.Canvas.png`
+
+:func:`vcs.Canvas.Canvas.portrait`
+
+:func:`vcs.Canvas.Canvas.postscript`
+
+:func:`vcs.Canvas.Canvas.processParameterChange`
+
+:func:`vcs.Canvas.Canvas.pstogif`
+
+:func:`vcs.Canvas.Canvas.put_png_on_canvas`
+
+:func:`vcs.Canvas.Canvas.raisecanvas`
+
+:func:`vcs.Canvas.Canvas.removeP`
+
+:func:`vcs.Canvas.Canvas.remove_display_name`
+
+:func:`vcs.Canvas.Canvas.removeobject`
+
+:func:`vcs.Canvas.Canvas.return_display_names`
+
+:func:`vcs.Canvas.Canvas.savecontinentstype`
+
+:func:`vcs.Canvas.Canvas.saveinitialfile`
+
+:func:`vcs.Canvas.Canvas.scalar3d`
+
+:func:`vcs.Canvas.Canvas.scatter`
+
+:func:`vcs.Canvas.Canvas.scriptobject`
+
+:func:`vcs.Canvas.Canvas.scriptrun`
+
+:func:`vcs.Canvas.Canvas.setAnimationStepper`
+
+:func:`vcs.Canvas.Canvas.setantialiasing`
+
+:func:`vcs.Canvas.Canvas.setbgoutputdimensions`
+
+:func:`vcs.Canvas.Canvas.setcolorcell`
+
+:func:`vcs.Canvas.Canvas.setcolormap`
+
+:func:`vcs.Canvas.Canvas.setcontinentsline`
+
+:func:`vcs.Canvas.Canvas.setcontinentstype`
+
+:func:`vcs.Canvas.Canvas.setdefaultfont`
+
+:func:`vcs.Canvas.Canvas.show`
+
+:func:`vcs.Canvas.Canvas.start`
+
+:func:`vcs.Canvas.Canvas.svg`
+
+:func:`vcs.Canvas.Canvas.switchfonts`
+
+:func:`vcs.Canvas.Canvas.taylordiagram`
+
+:func:`vcs.Canvas.Canvas.text`
+
+:func:`vcs.Canvas.Canvas.textcombined`
+
+:func:`vcs.Canvas.Canvas.update`
+
+:func:`vcs.Canvas.Canvas.updateorientation`
+
+:func:`vcs.Canvas.Canvas.vector`
+
+:func:`vcs.Canvas.Canvas.vector3d`
+
+:func:`vcs.Canvas.Canvas.xvsy`
+
+:func:`vcs.Canvas.Canvas.xyvsy`
+
+:func:`vcs.Canvas.Canvas.yxvsx`
+

docs/API/functions/animate_helper.rst

@@ -0,0 +1,5 @@
+animate_helper
+--------------
+
+:func:`vcs.animate_helper.showerror`
+

docs/API/functions/boxfill.rst

@@ -0,0 +1,29 @@
+boxfill
+-------
+
+:func:`vcs.boxfill.Gfb.colors`
+
+:func:`vcs.boxfill.Gfb.datawc`
+
+:func:`vcs.boxfill.Gfb.exts`
+
+:func:`vcs.boxfill.Gfb.getlegendlabels`
+
+:func:`vcs.boxfill.Gfb.getlevels`
+
+:func:`vcs.boxfill.Gfb.list`
+
+:func:`vcs.boxfill.Gfb.rename`
+
+:func:`vcs.boxfill.Gfb.script`
+
+:func:`vcs.boxfill.Gfb.xmtics`
+
+:func:`vcs.boxfill.Gfb.xticlabels`
+
+:func:`vcs.boxfill.Gfb.xyscale`
+
+:func:`vcs.boxfill.Gfb.ymtics`
+
+:func:`vcs.boxfill.Gfb.yticlabels`
+