Fix doc warnings (#222)

* address a bunch of warnings from building docs

* address some more warnings

* fix indentation issue with cleandoc

* apply suggestion from code review - replace todo with a fixme

* mock out envisage import if envisage is not available so we can build docs

* Revert "mock out envisage import if envisage is not available so we can build docs"

This reverts commit a8f383c.

* only mock envisage import for building documentation

* flake8

* move envisage import to options for autodoc section

apptools/io/h5/file.py

@@ -1,5 +1,6 @@
 from collections import Mapping, MutableMapping
 from functools import partial
+import inspect
 
 import numpy as np
 import tables
@@ -23,10 +24,10 @@ def _update_wrapped_docstring(wrapped, original=None):
 Note that the first argument is a nodepath relative to the group, rather than
 an absolute path. Below is the original docstring:
 
-    """.format(
+""".format(
         func_name=wrapped.__name__
     )
-    wrapped.__doc__ = PREAMBLE + original.__doc__
+    wrapped.__doc__ = PREAMBLE + inspect.cleandoc(original.__doc__)
     return wrapped
 
 

apptools/preferences/scoped_preferences.py

@@ -25,21 +25,21 @@ class ScopedPreferences(Preferences):
 
     Path names passed to 'ScopedPreferences' nodes can be either::
 
-    a) a preference path as used in a standard 'Preferences' node, e.g::
+        a) a preference path as used in a standard 'Preferences' node, e.g::
 
-       'acme.widget.bgcolor'.
+        'acme.widget.bgcolor'.
 
-       In this case the operation either takes place in the primary scope
-       (for operations such as 'set' etc), or on all scopes in precedence order
-       (for operations such as 'get' etc).
+        In this case the operation either takes place in the primary scope
+        (for operations such as 'set' etc), or on all scopes in precedence
+        order (for operations such as 'get' etc).
 
-    or
+        or
 
-    b) a preference path that refers to a specific scope e.g::
+        b) a preference path that refers to a specific scope e.g::
 
-       'default/acme.widget.bgcolor'
+        'default/acme.widget.bgcolor'
 
-       In this case the operation takes place *only* in the specified scope.
+        In this case the operation takes place *only* in the specified scope.
 
     There is one drawback to this scheme. If you want to access a scope node
     itself via the 'clear', 'keys', 'node', 'node_exists' or 'node_names'
@@ -48,23 +48,23 @@ class ScopedPreferences(Preferences):
 
     e.g. To get the names of the children of the 'application' scope, use::
 
-      scoped.node_names('application/')
+        scoped.node_names('application/')
 
     If you did this::
 
-      scoped.node_names('application')
+        scoped.node_names('application')
 
     Then the node would get the primary scope and try to find its child node
     called 'application'.
 
     Of course you can just get the scope via::
 
-      application_scope = scoped.get_scope('application')
+        application_scope = scoped.get_scope('application')
 
     and then call whatever methods you like on it - which is definitely more
     intentional and is highly recommended::
 
-      application_scope.node_names()
+        application_scope.node_names()
 
     """
 

apptools/preferences/ui/widget_editor.py

@@ -5,7 +5,7 @@
 from traits.api import Any
 from traitsui.api import EditorFactory
 from traitsui.toolkit import toolkit_object
-Editor = toolkit_object('editor.Editor')
+Editor = toolkit_object('editor:Editor')
 
 
 class _WidgetEditor(Editor):

apptools/scripting/recorder.py

@@ -1,9 +1,8 @@
 """
 Code to support recording to a readable and executable Python script.
 
-TODO:
+FIXME:
     - Support for dictionaries?
-
 """
 # Author: Prabhu Ramachandran <prabhu@aero.iitb.ac.in>
 # Copyright (c) 2008-2015, Enthought, Inc.
@@ -148,10 +147,11 @@ class Recorder(HasTraits):
     def record(self, code):
         """Record a string to be stored to the output file.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
 
-        code - A string of text.
+        code : str
+            A string of text.
         """
         if self.recording and not self._in_function:
             lines = self.lines
@@ -190,8 +190,8 @@ def register(
         If the `object` has a trait named `recorder` then this recorder
         instance will be set to it if possible.
 
-        Parameters:
-        -----------
+        Parameters
+        ----------
 
         object : Instance(HasTraits)
             The object to register in the registry.

apptools/scripting/util.py

@@ -15,8 +15,8 @@
 def start_recording(object, ui=True, **kw):
     """Convenience function to start recording.  Returns the recorder.
 
-    Parameters:
-    -----------
+    Parameters
+    ----------
 
     object :  object to record.
 

apptools/selection/errors.py

@@ -28,5 +28,5 @@ def __init__(self, provider_id, listener):
         self.listener = listener
 
     def __str__(self):
-        msg = "Selection listener {l} is not connected to provider '{id}'."
-        return msg.format(l=self.listener, id=self.provider_id)
+        msg = "Selection listener {lr} is not connected to provider '{id}'."
+        return msg.format(lr=self.listener, id=self.provider_id)

docs/source/conf.py

@@ -51,6 +51,18 @@
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
+# Options for autodoc
+# -------------------
+
+# Apptools offers an envisage plugin that requires importing from
+# envisage.
+try:
+    import envisage  # noqa
+except ImportError:
+    autodoc_mock_imports = [
+        'envisage',
+    ]
+
 # Options for HTML output
 # -----------------------
 

docs/source/selection/selection.rst

@@ -141,55 +141,4 @@ If the items specified in the arguments are not available in the provider,
 a :class:`~apptools.selection.errors.ProviderNotRegisteredError` is raised,
 unless the optional keyword argument :attr:`ignore_missing` is set to ``True``.
 
-
-API Reference
--------------
-
-:mod:`apptools.selection` Package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Users of the :mod:`apptools.selection` package can access the objects that are
-part of the public API through the convenience :mod:`apptools.selection.api`.
-
-:mod:`~apptools.selection.selection_service` Module
-'''''''''''''''''''''''''''''''''''''''''''''''''''
-
-.. automodule:: apptools.selection.selection_service
-        :members:
-        :undoc-members:
-        :show-inheritance:
-
-:mod:`~apptools.selection.i_selection_provider` Module
-''''''''''''''''''''''''''''''''''''''''''''''''''''''
-
-.. automodule:: apptools.selection.i_selection_provider
-        :members:
-        :undoc-members:
-        :show-inheritance:
-
-:mod:`~apptools.selection.is_selection` Module
-''''''''''''''''''''''''''''''''''''''''''''''
-
-.. automodule:: apptools.selection.i_selection
-        :members:
-        :undoc-members:
-        :show-inheritance:
-
-:mod:`~apptools.selection.list_selection` Module
-''''''''''''''''''''''''''''''''''''''''''''''''
-
-.. automodule:: apptools.selection.list_selection
-        :members:
-        :undoc-members:
-        :show-inheritance:
-
-:mod:`~apptools.selection.errors` Module
-''''''''''''''''''''''''''''''''''''''''''''''''
-
-.. automodule:: apptools.selection.errors
-        :members:
-        :undoc-members:
-        :show-inheritance:
-
-
 .. _envisage: http://docs.enthought.com/envisage/