docs: document TabStops and TabStop

Steve Canny · Steve Canny · commit 5cb582048903 · 2016-05-27T14:09:08.000-07:00
* fix some documentation bugs in the example code resulting from
  moving alignment and indent to ParagraphFormat.
diff --git a/docs/api/text.rst b/docs/api/text.rst
@@ -31,3 +31,19 @@ Text-related objects
 
 .. autoclass:: docx.text.run.Font()
    :members:
+
+
+|TabStop| objects
+-----------------
+
+.. autoclass:: docx.text.tabstops.TabStop()
+   :members:
+
+
+|TabStops| objects
+------------------
+
+.. autoclass:: docx.text.tabstops.TabStops()
+   :members: clear_all
+
+   .. automethod:: docx.text.tabstops.TabStops.add_tab_stop(position, alignment=WD_TAB_ALIGNMENT.LEFT, leader=WD_TAB_LEADER.SPACES)
diff --git a/docs/user/text.rst b/docs/user/text.rst
@@ -93,40 +93,87 @@ inheritance from the style hierarchy::
     >>> paragraph = document.add_paragraph()
     >>> paragraph_format = paragraph.paragraph_format
 
-    >>> paragraph.left_indent
+    >>> paragraph_format.left_indent
     None  # indicating indentation is inherited from the style hierarchy
-    >>> paragraph.left_indent = Inches(0.5)
-    >>> paragraph.left_indent
+    >>> paragraph_format.left_indent = Inches(0.5)
+    >>> paragraph_format.left_indent
     457200
-    >>> paragraph.left_indent.inches
+    >>> paragraph_format.left_indent.inches
     0.5
 
 
 Right-side indent works in a similar way::
 
     >>> from docx.shared import Pt
-    >>> paragraph.right_indent
+    >>> paragraph_format.right_indent
     None
-    >>> paragraph.right_indent = Pt(24)
-    >>> paragraph.right_indent
+    >>> paragraph_format.right_indent = Pt(24)
+    >>> paragraph_format.right_indent
     304800
-    >>> paragraph.right_indent.pt
+    >>> paragraph_format.right_indent.pt
     24.0
 
 
+
+
 First-line indent is specified using the
 :attr:`~.ParagraphFormat.first_line_indent` property and is interpreted
 relative to the left indent. A negative value indicates a hanging indent::
 
-    >>> paragraph.first_line_indent
+    >>> paragraph_format.first_line_indent
     None
-    >>> paragraph.first_line_indent = Inches(-0.25)
-    >>> paragraph.first_line_indent
+    >>> paragraph_format.first_line_indent = Inches(-0.25)
+    >>> paragraph_format.first_line_indent
     -228600
-    >>> paragraph.first_line_indent.inches
+    >>> paragraph_format.first_line_indent.inches
     -0.25
 
 
+Tab stops
+~~~~~~~~~
+
+A tab stop determines the rendering of a tab character in the text of
+a paragraph. In particular, it specifies the position where the text
+following the tab character will start, how it will be aligned to that
+position, and an optional leader character that will fill the horizontal
+space spanned by the tab.
+
+The tab stops for a paragraph or style are contained in a |TabStops| object
+accessed using the :attr:`~.ParagraphFormat.tab_stops` property on
+|ParagraphFormat|::
+
+    >>> tab_stops = paragraph_format.tab_stops
+    >>> tab_stops
+    <docx.text.tabstops.TabStops object at 0x106b802d8>
+
+A new tab stop is added using the :meth:`~.TabStops.add_tab_stop` method::
+
+    >>> tab_stop = tab_stops.add_tab_stop(Inches(1.5))
+    >>> tab_stop.position
+    1371600
+    >>> tab_stop.position.inches
+    1.5
+
+Alignment defaults to left, but may be specified by providing a member of the
+:ref:`WdTabAlignment` enumeration. The leader character defaults to spaces,
+but may be specified by providing a member of the :ref:`WdTabLeader`
+enumeration::
+
+    >>> from docx.enum.text import WD_TAB_ALIGNMENT, WD_TAB_LEADER
+    >>> tab_stop = tab_stops.add_tab_stop(Inches(1.5), WD_TAB_ALIGNMENT.RIGHT, WD_TAB_LEADER.DOTS)
+    >>> print(tab_stop.alignment)
+    RIGHT (2)
+    >>> print(tab_stop.leader)
+    DOTS (1)
+
+Existing tab stops are accessed using sequence semantics on |TabStops|::
+
+    >>> tab_stops[0]
+    <docx.text.tabstops.TabStop object at 0x1105427e8>
+
+More details are available in the |TabStops| and |TabStop| API documentation
+
+
 Paragraph spacing
 ~~~~~~~~~~~~~~~~~
 
@@ -177,7 +224,7 @@ of the :ref:`WdLineSpacing` enumeration or |None|::
     None
 
     >>> paragraph_format.line_spacing = Pt(18)
-    >>> isinstance(Length, paragraph_format.line_spacing)
+    >>> isinstance(paragraph_format.line_spacing, Length)
     True
     >>> paragraph_format.line_spacing.pt
     18.0
diff --git a/docx/text/tabstops.py b/docx/text/tabstops.py
@@ -14,10 +14,11 @@
 
 class TabStops(ElementProxy):
     """
-    A sequence providing access to the tab stops of a paragraph or paragraph
-    style. Supports iteration, indexed access, del, and len(). It is accesed
-    using the `tab_stops` property of ParagraphFormat; it is not intended to
-    be constructed directly.
+    A sequence of |TabStop| objects providing access to the tab stops of
+    a paragraph or paragraph style. Supports iteration, indexed access, del,
+    and len(). It is accesed using the :attr:`~.ParagraphFormat.tab_stops`
+    property of ParagraphFormat; it is not intended to be constructed
+    directly.
     """
 
     __slots__ = ('_pPr')
@@ -68,11 +69,13 @@ def __len__(self):
     def add_tab_stop(self, position, alignment=WD_TAB_ALIGNMENT.LEFT,
                      leader=WD_TAB_LEADER.SPACES):
         """
-        Add a new tab stop at *position*. Tab alignment defaults to left, but
-        may be specified by passing a member of the :ref:`WdTabAlignment`
-        enumeration as *alignment*. An optional leader character can be
-        specified by passing a member of the :ref:`WdTabLeader` enumeration
-        as *leader*.
+        Add a new tab stop at *position*, a |Length| object specifying the
+        location of the tab stop relative to the paragraph edge. A negative
+        *position* value is valid and appears in hanging indentation. Tab
+        alignment defaults to left, but may be specified by passing a member
+        of the :ref:`WdTabAlignment` enumeration as *alignment*. An optional
+        leader character can be specified by passing a member of the
+        :ref:`WdTabLeader` enumeration as *leader*.
         """
         tabs = self._pPr.get_or_add_tabs()
         tab = tabs.insert_tab_in_order(position, alignment, leader)
@@ -87,8 +90,8 @@ def clear_all(self):
 
 class TabStop(ElementProxy):
     """
-    An individual tab stop applying to a paragraph or style. Each of these is
-    a member of a set held in a |TabStops| object.
+    An individual tab stop applying to a paragraph or style. Accessed using
+    list semantics on its containing |TabStops| object.
     """
 
     __slots__ = ('_tab')
@@ -101,7 +104,7 @@ def __init__(self, element):
     def alignment(self):
         """
         A member of :ref:`WdTabAlignment` specifying the alignment setting
-        for this tab stop.
+        for this tab stop. Read/write.
         """
         return self._tab.val
 
@@ -115,6 +118,7 @@ def leader(self):
         A member of :ref:`WdTabLeader` specifying a repeating character used
         as a "leader", filling in the space spanned by this tab. Assigning
         |None| produces the same result as assigning `WD_TAB_LEADER.SPACES`.
+        Read/write.
         """
         return self._tab.leader
 
@@ -125,8 +129,9 @@ def leader(self, value):
     @property
     def position(self):
         """
-        The distance (in EMU) of this tab stop from the inside edge of the
-        paragraph. May be positive or negative.
+        A |Length| object representing the distance of this tab stop from the
+        inside edge of the paragraph. May be positive or negative.
+        Read/write.
         """
         return self._tab.pos
 
