docs: add user documentation for sections

Steve Canny · Steve Canny · commit 164b4af57af5 · 2014-06-22T14:10:38.000-07:00
diff --git a/docs/api/document.rst b/docs/api/document.rst
@@ -4,7 +4,7 @@
 Document objects
 ================
 
-... things having to do with Document objects ...
+The main Document and related objects.
 
 
 .. currentmodule:: docx.api
@@ -16,3 +16,15 @@ Document objects
 
 .. autoclass:: Document
    :members:
+   :exclude-members: numbering_part, styles_part
+
+
+.. currentmodule:: docx.parts.document
+
+
+|Sections| objects
+------------------
+
+
+.. autoclass:: Sections
+   :members:
diff --git a/docs/api/enum/WdOrientation.rst b/docs/api/enum/WdOrientation.rst
@@ -0,0 +1,23 @@
+.. _WdOrientation:
+
+``WD_ORIENTATION``
+==================
+
+alias: **WD_ORIENT**
+
+Specifies the page layout orientation.
+
+Example::
+
+    from docx.enum.section import WD_ORIENT
+
+    section = document.sections[-1]
+    section.orientation = WD_ORIENT.LANDSCAPE
+
+----
+
+PORTRAIT
+    Portrait orientation.
+
+LANDSCAPE
+    Landscape orientation.
diff --git a/docs/api/enum/WdSectionStart.rst b/docs/api/enum/WdSectionStart.rst
@@ -0,0 +1,32 @@
+.. _WdSectionStart:
+
+``WD_SECTION_START``
+====================
+
+alias: **WD_SECTION**
+
+Specifies the start type of a section break.
+
+Example::
+
+    from docx.enum.section import WD_SECTION
+
+    section = document.sections[0]
+    section.start_type = WD_SECTION.NEW_PAGE
+
+----
+
+CONTINUOUS
+    Continuous section break.
+
+NEW_COLUMN
+    New column section break.
+
+NEW_PAGE
+    New page section break.
+
+EVEN_PAGE
+    Even pages section break.
+
+ODD_PAGE
+    Section begins on next odd page.
diff --git a/docs/api/enum/index.rst b/docs/api/enum/index.rst
@@ -8,4 +8,6 @@ can be found here:
 .. toctree::
    :titlesonly:
 
+   WdOrientation
+   WdSectionStart
    WdUnderline
diff --git a/docs/api/section.rst b/docs/api/section.rst
@@ -0,0 +1,18 @@
+
+.. _section_api:
+
+Section objects
+===============
+
+Provides access to section properties such as margins and page orientation.
+
+
+.. currentmodule:: docx.section
+
+
+|Section| objects
+-----------------
+
+
+.. autoclass:: Section
+   :members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -77,7 +77,7 @@
 
 .. |_Columns| replace:: :class:`_Columns`
 
-.. |Document| replace:: :class:`Document`
+.. |Document| replace:: :class:`.Document`
 
 .. |docx| replace:: ``python-docx``
 
@@ -117,7 +117,7 @@
 
 .. |Sections| replace:: :class:`.Sections`
 
-.. |StylesPart| replace:: :class:`StylesPart`
+.. |StylesPart| replace:: :class:`.StylesPart`
 
 .. |Table| replace:: :class:`.Table`
 
diff --git a/docs/dev/analysis/features/sections.rst b/docs/dev/analysis/features/sections.rst
@@ -32,54 +32,6 @@ occur:
    element is changed to reflect the type chosen by the user from the UI.
 
 
-Candidate protocol
-------------------
-
-The following interactive session demonstrates the proposed protocol for
-inserting a section break, illustrating adding a landscape section after an
-existing portrait section::
-
-    >>> section_1 = document.sections[0]
-    >>> document.add_paragraph('This paragraph appears in section 1.')
-    >>> section_2 = document.add_section(WD_SECTION.EVEN_PAGE)
-    >>> section_2.orientation
-    PORTRAIT (0)
-    >>> section_2.orientation = WD_ORIENT.LANDSCAPE
-    >>> section_2.page_width = section_1.page_height
-    >>> section_2.page_height = section_1.page_width
-    >>> document.add_paragraph('This paragraph appears in section 2.')
-
-
-The following interactive session demonstrates the proposed protocol for
-setting section properties::
-
-    >>> sections = document.sections
-    >>> sections
-    <docx.parts.document.Sections object at 0x1deadbeef>
-    >>> len(sections)
-    3
-    >>> section = sections[-1]  # the sentinel section
-    >>> section
-    <docx.section.Section object at 0x1deadbeef>
-    >>> section.section_start
-    WD_SECTION.CONTINUOUS (0)
-    >>> page_setup = section.page_setup
-    >>> page_setup
-    <docx.section.PageSetup object at 0x1deadbeef>
-    >>> page_setup.page_width
-    7772400  # Inches(8.5)
-    >>> page_setup.page_height
-    10058400  # Inches(11)
-    >>> page_setup.orientation
-    WD_ORIENT.PORTRAIT
-    >>> page_setup.left_margin  # and .right_, .top_, .bottom_
-    914400
-    >>> page_setup.header_distance  # and .footer_distance
-    457200  # Inches(0.5)
-    >>> page_setup.gutter
-    0
-
-
 Word behavior
 -------------
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -67,6 +67,7 @@ User Guide
    user/install
    user/quickstart
    user/documents
+   user/sections
    user/api-concepts
    user/styles
    user/shapes
@@ -82,6 +83,7 @@ API Documentation
    api/document
    api/table
    api/text
+   api/section
    api/shape
    api/shared
    api/enum/index
diff --git a/docs/user/sections.rst b/docs/user/sections.rst
@@ -0,0 +1,122 @@
+.. _sections:
+
+Working with Sections
+=====================
+
+Word supports the notion of a *section*, a division of a document having the
+same page layout settings, such as margins and page orientation. This is how,
+for example, a document can contain some pages in portrait layout and others in
+landscape.
+
+Most Word documents have only the single section that comes by default and
+further, most of those have no reason to change the default margins or other
+page layout. But when you *do* need to change the page layout, you'll need
+to understand sections to get it done.
+
+
+Accessing sections
+------------------
+
+Access to document sections is provided by the ``sections`` property on the
+|Document| object::
+
+    >>> document = Document()
+    >>> sections = document.sections
+    >>> sections
+    <docx.parts.document.Sections object at 0x1deadbeef>
+    >>> len(sections)
+    3
+    >>> section = sections[0]
+    >>> section
+    <docx.section.Section object at 0x1deadbeef>
+    >>> for section in sections:
+    ...     print(section.start_type)
+    ...
+    NEW_PAGE (2)
+    EVEN_PAGE (3)
+    ODD_PAGE (4)
+
+It's theoretically possible for a document not to have any explicit sections,
+although I've yet to see this occur in the wild. If you're accessing an
+unpredictable population of .docx files you may want to provide for that
+possibility using a ``len()`` check or ``try`` block to avoid an uncaught
+``IndexError`` exception stopping your program.
+
+
+Adding a new section
+--------------------
+
+.. currentmodule:: docx.api
+
+The :meth:`Document.add_section` method allows a new section to be started at
+the end of the document. Paragraphs and tables added after calling this method
+will appear in the new section::
+
+    >>> current_section = document.section[-1]  # last section in document
+    >>> current_section.start_type
+    NEW_PAGE (2)
+    >>> new_section = document.add_section(WD_SECTION.ODD_PAGE)
+    >>> new_section.start_type
+    ODD_PAGE (4)
+
+
+Section properties
+------------------
+
+.. currentmodule:: docx.section
+
+The |Section| object has eleven properties that allow page layout settings to
+be discovered and specified.
+
+
+Section start type
+~~~~~~~~~~~~~~~~~~
+
+:attr:`Section.start_type` describes the type of break that precedes the
+section::
+
+    >>> section.start_type
+    NEW_PAGE (2)
+    >>> section.start_type = WD_SECTION.ODD_PAGE
+    >>> section.start_type
+    ODD_PAGE (4)
+
+Values of ``start_type`` are members of the :ref:`WdSectionStart` enumeration.
+
+
+Page dimensions and orientation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Three properties on |Section| describe page dimensions and orientation.
+Together these can be used, for example, to change the orientation of a section
+from portrait to landscape::
+
+    >>> section.orientation, section.page_width, section.page_height
+    (PORTRAIT (0), 7772400, 10058400)  # (Inches(8.5), Inches(11))
+    >>> new_width, new_height = section.page_height, section.page_width
+    >>> section.orientation = WD_ORIENT.LANDSCAPE
+    >>> section.page_width = new_width
+    >>> section.page_height = new_height
+    >>> section.orientation, section.page_width, section.page_height
+    (LANDSCAPE (1), 10058400, 7772400) 
+
+
+Page margins
+~~~~~~~~~~~~
+
+Seven properties on |Section| together specify the various edge spacings that
+determine where text appears on the page::
+
+    >>> from docx.shared import Inches
+    >>> section.left_margin, section.right_margin
+    (1143000, 1143000)  # (Inches(1.25), Inches(1.25))
+    >>> section.top_margin, section.bottom_margin
+    (914400, 914400)  # (Inches(1), Inches(1))
+    >>> section.gutter
+    0
+    >>> section.header_distance, section.footer_distance
+    (457200, 457200)  # (Inches(0.5), Inches(0.5))
+    >>> section.left_margin = Inches(1.5)
+    >>> section.right_margin = Inches(1)
+    >>> section.left_margin, section.right_margin
+    (1371600, 914400)
diff --git a/docx/api.py b/docx/api.py
@@ -104,7 +104,9 @@ def add_picture(self, image_path_or_stream, width=None, height=None):
     def add_section(self, start_type=WD_SECTION.NEW_PAGE):
         """
         Return a |Section| object representing a new section added at the end
-        of the document.
+        of the document. The optional *start_type* argument must be a member
+        of the :ref:`WdSectionStart` enumeration defaulting to
+        ``WD_SECTION.NEW_PAGE`` if not provided.
         """
         return self._document_part.add_section(start_type)
 
diff --git a/docx/enum/section.py b/docx/enum/section.py
@@ -12,7 +12,16 @@
 @alias('WD_ORIENT')
 class WD_ORIENTATION(XmlEnumeration):
     """
+    alias: **WD_ORIENT**
+
     Specifies the page layout orientation.
+
+    Example::
+
+        from docx.enum.section import WD_ORIENT
+
+        section = document.sections[-1]
+        section.orientation = WD_ORIENT.LANDSCAPE
     """
 
     __ms_name__ = 'WdOrientation'
@@ -32,7 +41,16 @@ class WD_ORIENTATION(XmlEnumeration):
 @alias('WD_SECTION')
 class WD_SECTION_START(XmlEnumeration):
     """
+    alias: **WD_SECTION**
+
     Specifies the start type of a section break.
+
+    Example::
+
+        from docx.enum.section import WD_SECTION
+
+        section = document.sections[0]
+        section.start_type = WD_SECTION.NEW_PAGE
     """
 
     __ms_name__ = 'WdSectionStart'
diff --git a/docx/parts/document.py b/docx/parts/document.py
@@ -239,7 +239,7 @@ def _inline_lst(self):
 class Sections(Sequence):
     """
     Sequence of |Section| objects corresponding to the sections in the
-    document.
+    document. Supports ``len()``, iteration, and indexed access.
     """
     def __init__(self, document_elm):
         super(Sections, self).__init__()
diff --git a/docx/section.py b/docx/section.py
@@ -82,7 +82,8 @@ def left_margin(self, value):
     @property
     def orientation(self):
         """
-        Page orientation for this section, one of ``WD_ORIENT.PORTRAIT`` or
+        Member of the :ref:`WdOrientation` enumeration specifying the page
+        orientation for this section, one of ``WD_ORIENT.PORTRAIT`` or
         ``WD_ORIENT.LANDSCAPE``.
         """
         return self._sectPr.orientation
@@ -134,9 +135,10 @@ def right_margin(self, value):
     @property
     def start_type(self):
         """
-        The member of the ``WD_SECTION`` enumeration corresponding to the
-        initial break behavior of this section, e.g. ``WD_SECTION.ODD_PAGE``
-        if the section should begin on the next odd page.
+        The member of the :ref:`WdSectionStart` enumeration corresponding to
+        the initial break behavior of this section, e.g.
+        ``WD_SECTION.ODD_PAGE`` if the section should begin on the next odd
+        page.
         """
         return self._sectPr.start_type
 
