docs: add API page for docx.styles.style module

Steve Canny · Steve Canny · commit b7ec0f07e454 · 2015-02-08T00:01:45.000-08:00
diff --git a/docs/api/style.rst b/docs/api/style.rst
@@ -0,0 +1,63 @@
+
+.. _style_api:
+
+Style-related objects
+=====================
+
+A style is used to collect a set of formatting properties under a single name
+and apply those properties to a content object all at once. This promotes
+formatting consistency thoroughout a document and across related documents
+and allows formatting changes to be made globally by changing the definition
+in the appropriate style.
+
+.. currentmodule:: docx.styles.style
+
+
+|BaseStyle| objects
+-------------------
+
+.. autoclass:: BaseStyle()
+   :members:
+   :inherited-members:
+   :exclude-members:
+       part, style_id
+
+
+|_CharacterStyle| objects
+-------------------------
+
+.. autoclass:: _CharacterStyle()
+   :show-inheritance:
+   :members:
+   :inherited-members:
+   :exclude-members:
+       element, part, style_id, type
+
+
+|_ParagraphStyle| objects
+-------------------------
+
+.. autoclass:: _ParagraphStyle()
+   :show-inheritance:
+   :members:
+   :inherited-members:
+   :exclude-members:
+       element, part, style_id, type
+
+
+|_TableStyle| objects
+---------------------
+
+.. autoclass:: _TableStyle()
+   :show-inheritance:
+   :members:
+   :inherited-members:
+   :exclude-members:
+       element, part, style_id, type
+
+
+|_NumberingStyle| objects
+-------------------------
+
+.. autoclass:: _NumberingStyle()
+   :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -69,10 +69,14 @@
 rst_epilog = """
 .. |api-Document| replace:: :class:`docx.api.Document`
 
+.. |BaseStyle| replace:: :class:`.BaseStyle`
+
 .. |_Body| replace:: :class:`._Body`
 
 .. |_Cell| replace:: :class:`._Cell`
 
+.. |_CharacterStyle| replace:: :class:`._CharacterStyle`
+
 .. |Cm| replace:: :class:`.Cm`
 
 .. |_Column| replace:: :class:`._Column`
@@ -109,16 +113,20 @@
 
 .. |Length| replace:: :class:`.Length`
 
-.. |OpcPackage| replace:: :class:`.OpcPackage`
-
 .. |None| replace:: :class:`.None`
 
 .. |NumberingPart| replace:: :class:`.NumberingPart`
 
+.. |_NumberingStyle| replace:: :class:`._NumberingStyle`
+
+.. |OpcPackage| replace:: :class:`.OpcPackage`
+
 .. |Paragraph| replace:: :class:`.Paragraph`
 
 .. |ParagraphFormat| replace:: :class:`.ParagraphFormat`
 
+.. |_ParagraphStyle| replace:: :class:`._ParagraphStyle`
+
 .. |Part| replace:: :class:`.Part`
 
 .. |Pt| replace:: :class:`.Pt`
@@ -147,6 +155,8 @@
 
 .. |Table| replace:: :class:`.Table`
 
+.. |_TableStyle| replace:: :class:`._TableStyle`
+
 .. |_Text| replace:: :class:`._Text`
 
 .. |True| replace:: :class:`True`
diff --git a/docs/index.rst b/docs/index.rst
@@ -83,8 +83,9 @@ API Documentation
    :maxdepth: 2
 
    api/document
-   api/table
+   api/style
    api/text
+   api/table
    api/section
    api/shape
    api/shared
diff --git a/docx/styles/style.py b/docx/styles/style.py
@@ -32,16 +32,19 @@ def StyleFactory(style_elm):
 class BaseStyle(ElementProxy):
     """
     Base class for the various types of style object, paragraph, character,
-    table, and numbering.
+    table, and numbering. These properties and methods are inherited by all
+    style objects.
     """
 
     __slots__ = ()
 
     @property
     def builtin(self):
         """
-        Boolean indicating whether this style is a built-in style. False
-        indicates it is a custom (user-defined) style.
+        Read-only. |True| if this style is a built-in style. |False|
+        indicates it is a custom (user-defined) style. Note this value is
+        based on the presence of a `customStyle` attribute in the XML, not on
+        specific knowledge of which styles are built into Word.
         """
         return not self._element.customStyle
 
@@ -73,7 +76,9 @@ def name(self, value):
     @property
     def style_id(self):
         """
-        The unique key name (string) for this style.
+        The unique key name (string) for this style. This value is subject to
+        rewriting by Word and should generally not be changed unless you are
+        familiar with the internals involved.
         """
         return self._element.styleId
 
@@ -85,7 +90,7 @@ def style_id(self, value):
     def type(self):
         """
         Member of :ref:`WdStyleType` corresponding to the type of this style,
-        e.g. ``WD_STYLE_TYPE.PARAGRAPH`.
+        e.g. ``WD_STYLE_TYPE.PARAGRAPH``.
         """
         type = self._element.type
         if type is None:
@@ -115,7 +120,9 @@ def _translate_special_case_names(name):
 
 class _CharacterStyle(BaseStyle):
     """
-    A character style.
+    A character style. A character style is applied to a |Run| object and
+    primarily provides character-level formatting via the |Font| object in
+    its :attr:`.font` property.
     """
 
     __slots__ = ()
@@ -147,7 +154,8 @@ def font(self):
 
 class _ParagraphStyle(_CharacterStyle):
     """
-    A paragraph style.
+    A paragraph style. A paragraph style provides both character formatting
+    and paragraph formatting such as indentation and line-spacing.
     """
 
     __slots__ = ()
@@ -156,22 +164,23 @@ class _ParagraphStyle(_CharacterStyle):
     def paragraph_format(self):
         """
         The |ParagraphFormat| object providing access to the paragraph
-        properties for this style.
+        formatting properties for this style such as indentation.
         """
         return ParagraphFormat(self._element)
 
 
 class _TableStyle(_ParagraphStyle):
     """
-    A table style.
+    A table style. A table style provides character and paragraph formatting
+    for its contents as well as special table formatting properties.
     """
 
     __slots__ = ()
 
 
 class _NumberingStyle(BaseStyle):
     """
-    A numbering style.
+    A numbering style. Not yet implemented.
     """
 
     __slots__ = ()
