More Docs. Reorganized Index

gtalarico · Oct 3, 2017 · 8ac5a38 · 8ac5a38
1 parent a13e060
commit 8ac5a38
Show file tree

Hide file tree

Showing 6 changed files with 51 additions and 51 deletions.
diff --git a/docs/source/exceptions.rst b/docs/source/exceptions.rst
@@ -5,10 +5,15 @@
 
 
 ==================
-Exceptions
+rpw.exceptions
 ==================
 
-Revit Python Wrapper Exceptions
+Overview
+*******************************
+
+.. automodule:: rpw.exceptions
+
+Custom Exceptions
 *******************************
 
 .. automodule:: rpw.exceptions

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,26 +7,6 @@
 Revit Python Wrapper
 ====================
 
-
-.. toctree::
-   :maxdepth: 3
-   :hidden:
-
-   self
-   revit
-   db
-   ui
-   base
-   utils
-   extras
-
-   installation
-
-   exceptions
-   known_issues
-   tests
-
-
 .. image:: ../_static/logo/logo-tight.png
   :scale: 50%
 
@@ -46,7 +26,7 @@ Wrapper classes make the interaction with API objects less repetitive,
 and more consistent with Python's conventions.
 
 .. caution::
-    | Rpw 1.0 has taught use many lessons. Some API breaking changes are expected on 2.0 release (Q4 2017)
+    | API breaking changes are expected on 2.0 release (Q4 2017)
 
 Questions? Post them over in the project's `Github Page <http://www.github.com/gtalarico/revitpythonwrapper>`_ or
 hit me up on `twitter <https://twitter.com/gtalarico>`_.
@@ -130,7 +110,32 @@ To minimize namespace collisions, the patterns below are highly recommended:
 
 
 **********************************
-Basic Components
+Contents
+**********************************
+
+:ref:`genindex` | :ref:`modindex`
+
+.. toctree::
+   :maxdepth: 2
+
+   self
+   installation
+
+   revit
+   db
+   ui
+   base
+   utils
+   extras
+   exceptions
+
+   known_issues
+   tests
+
+---------------------------------------------------------------------------------
+
+**********************************
+Quick Overview and Comparison
 **********************************
 
 The examples below give a basic overview of how the library is used,
@@ -308,22 +313,3 @@ Without RPW
     >>> form = SelectFromList('Window Title', options)
     >>> form.show()
     >>> selected_item = form.selected
-
-
-:doc:`utils`
-^^^^^^^^^^^^^^^^^^^
-
-    >>> # Handy Batch Converters to and from Element / ElementIds
-    >>> rpw.utils.to_elements(DB.ElementId)
-    [ DB.Element ]
-    >>> rpw.utils.to_elements(20001)
-    [ DB.Element ]
-    >>> rpw.utils.to_elements([20001, 20003])
-    [ DB.Element, DB.Element ]
-
-    >>> rpw.utils.to_element_ids(DB.Element)
-    [ DB.ElementId ]
-    >>> rpw.utils.to_element_ids(20001)
-    [ DB.ElementId ]
-    >>> rpw.utils.to_element_ids([20001, 20003])
-    [ DB.ElementId, DB.ElementId ]
diff --git a/docs/source/known_issues.rst b/docs/source/known_issues.rst
@@ -13,6 +13,13 @@ Known Issues
     element is returned, sometimes is unwrapped.
     Since fixing this would be a breaking change, I am panning on
     fixing this on the next major release (2.0)
+    The main change will be that attributes that were previously properties,
+    will become a get method with an optional kwarg for wrapped:
+
+    >>> # Previous
+    >>> instance.family
+    >>> # 2.0
+    >>> instance.get_family()
 
 * Case Sensitive ElementParameterFilter
 

diff --git a/rpw/base.py b/rpw/base.py
@@ -70,9 +70,12 @@ def __init__(self, revit_object, enforce_type=True):
 
         Warning:
             Any Wrapper that inherits and overrides __init__ class MUST
-            super to ensure _revit_object is created by calling super().__init__
-            BaseObjectWrapper must define a class variable _revit_object_class
-            to define the object being wrapped.
+            ensure ``_revit_object`` is created by calling super().__init__
+            before setting any self attributes. Not doing so will
+            cause recursion errors and Revit will crash.
+            BaseObjectWrapper should define a class variable _revit_object_class
+            to define the object class being wrapped.
+
         """
         _revit_object_class = self.__class__._revit_object_class
 

diff --git a/rpw/exceptions.py b/rpw/exceptions.py
@@ -1,7 +1,5 @@
 """
-Custom RPW exceptions
-
-Use these exceptions to _try_ against specific Rpw Exceptions.
+Use these exceptions to `try` against specific Rpw Exceptions.
 
 >>> from rpw.exceptions import RpwWrongStorageType
 >>> try:
@@ -10,10 +8,10 @@
 ...     print('Height Parameter cannot be a string')
 ...     raise
 
-This module also provides easy access to the Autodesk.Revit.Exceptions
+This module also provides easy access to the ``Autodesk.Revit.Exceptions``
 namespaces:
 
->>> from rpw.exceptions import OperationCanceledException
+>>> from rpw.exceptions import InvalidObjectException
 >>> try:
 ...     doc.Delete(ElementId)
 ... except InvalidObjectException:

diff --git a/rpw/utils/coerce.py b/rpw/utils/coerce.py
@@ -61,6 +61,7 @@ def to_element_ids(element_references):
 
 # TODO: Add case to unwrap rpw elements
 def to_element(element_reference, doc=revit.doc):
+    """ Same as to_elements but for a single object """
     if isinstance(element_reference, DB.ElementId):
         element = doc.GetElement(element_reference)
     elif isinstance(element_reference, DB.Reference):