docs: add API docs for header/footer

scanny · scanny · commit a2df1d10c003 · 2019-01-06T14:26:12.000-08:00
diff --git a/docs/api/section.rst b/docs/api/section.rst
@@ -22,4 +22,20 @@ Provides access to section properties such as margins and page orientation.
 
 
 .. autoclass:: Section
-   :members:
+   :members: 
+
+
+|_Header| and |_Footer| objects
+-------------------------------
+
+
+.. autoclass:: _Header()
+   :inherited-members: 
+   :members: 
+   :exclude-members: part
+
+
+.. autoclass:: _Footer()
+   :inherited-members: 
+   :members: 
+   :exclude-members: part
diff --git a/docs/conf.py b/docs/conf.py
@@ -109,8 +109,12 @@
 
 .. |_Footer| replace:: :class:`._Footer`
 
+.. |FooterPart| replace:: :class:`.FooterPart`
+
 .. |_Header| replace:: :class:`._Header`
 
+.. |HeaderPart| replace:: :class:`.HeaderPart`
+
 .. |ImageParts| replace:: :class:`.ImageParts`
 
 .. |Inches| replace:: :class:`.Inches`
diff --git a/docx/section.py b/docx/section.py
@@ -79,7 +79,7 @@ def even_page_footer(self):
         """|_Footer| object defining footer content for even pages.
 
         The content of this footer definition is ignored unless the document setting
-        :attr:`~Settings.odd_and_even_pages_header_footer` is set True.
+        :attr:`~.Settings.odd_and_even_pages_header_footer` is set True.
         """
         return _Footer(self._sectPr, self._document_part,  WD_HEADER_FOOTER.EVEN_PAGE)
 
@@ -88,7 +88,7 @@ def even_page_header(self):
         """|_Header| object defining header content for even pages.
 
         The content of this header definition is ignored unless the document setting
-        :attr:`~Settings.odd_and_even_pages_header_footer` is set True.
+        :attr:`~.Settings.odd_and_even_pages_header_footer` is set True.
         """
         return _Header(self._sectPr, self._document_part, WD_HEADER_FOOTER.EVEN_PAGE)
 
@@ -106,7 +106,7 @@ def first_page_header(self):
         """|_Header| object defining header content for the first page of this section.
 
         The content of this header definition is ignored unless the property
-        :attr:`.different_first_page_header_header` is set True.
+        :attr:`.different_first_page_header_footer` is set True.
         """
         return _Header(self._sectPr, self._document_part, WD_HEADER_FOOTER.FIRST_PAGE)
 
@@ -270,9 +270,9 @@ def __init__(self, sectPr, document_part, header_footer_index):
 
     @property
     def is_linked_to_previous(self):
-        """True if this header/footer uses the definition from the preceding section.
+        """``True`` if this header/footer uses the definition from the prior section.
 
-        False if this header/footer has an explicit definition.
+        ``False`` if this header/footer has an explicit definition.
 
         Assigning ``True`` to this property removes the header/footer definition for
         this section, causing it to "inherit" the corresponding definition of the prior
@@ -357,7 +357,14 @@ def _prior_headerfooter(self):
 
 
 class _Footer(_BaseHeaderFooter):
-    """Page footer."""
+    """Page footer, used for all three types (default, even-page, and first-page).
+
+    Note that, like a document or table cell, a footer must contain a minimum of one
+    paragraph and a new or otherwise "empty" footer contains a single empty paragraph.
+    This first paragraph can be accessed as `footer.paragraphs[0]` for purposes of
+    adding content to it. Using :meth:`add_paragraph()` by itself to add content will
+    leave an empty paragraph above the newly added one.
+    """
 
     def _add_definition(self):
         """Return newly-added footer part."""
@@ -393,7 +400,14 @@ def _prior_headerfooter(self):
 
 
 class _Header(_BaseHeaderFooter):
-    """Page header."""
+    """Page header, used for all three types (default, even-page, and first-page).
+
+    Note that, like a document or table cell, a header must contain a minimum of one
+    paragraph and a new or otherwise "empty" header contains a single empty paragraph.
+    This first paragraph can be accessed as `header.paragraphs[0]` for purposes of
+    adding content to it. Using :meth:`add_paragraph()` by itself to add content will
+    leave an empty paragraph above the newly added one.
+    """
 
     def _add_definition(self):
         """Return newly-added header part."""
