docs: add shapes page to user guide

Steve Canny · Steve Canny · commit ad99e19465ca · 2014-01-02T04:52:03.000-08:00
diff --git a/docs/api/document.rst b/docs/api/document.rst
@@ -10,8 +10,9 @@ Document objects
 .. currentmodule:: docx.api
 
 
-|_Document| objects
--------------------
+|Document| objects
+------------------
 
-.. autoclass:: _Document
+
+.. autoclass:: Document
    :members:
diff --git a/docs/index.rst b/docs/index.rst
@@ -21,42 +21,44 @@ A post-alpha release is expected within a few weeks, say Feb 1, 2014.
 What it can do
 --------------
 
+.. |img| image:: /_static/img/example-docx-01.png
+
 Here's an example of what |docx| can do:
 
-.. figure:: /_static/img/example-docx-01.png
+======  ======================================================================
+|img|   ::
+
+          from docx import Document
 
-|
+          document = Document()
 
-::
+          document.add_heading('Document Title', 0)
+          document.add_paragraph('A plain paragraph.')
 
-    from docx import Document
+          document.add_heading('Heading, level 1', level=1)
+          document.add_paragraph('Intense quote', style='IntenseQuote')
 
-    document = Document()
+          document.add_bullet('first item in unordered list')
+          document.add_list_item('first item in ordered list')
 
-    document.add_heading('Document Title', 0)
-    document.add_paragraph('A plain paragraph.')
-    document.add_heading('Heading, level 1', level=1)
-    document.add_paragraph('Intense quote', style='IntenseQuote')
-    document.add_bullet('first item in unordered list')
-    document.add_list_item('first item in ordered list')
+          document.add_picture('monty-truth.png')
 
-    document.add_picture('monty-truth.png')
+          table = document.add_table(rows=1, cols=3)
+          table.style = 'LightShading-Accent1'
+          header_cells = table.rows[0].cells
+          header_cells[0].text = 'Qty'
+          header_cells[1].text = 'Id'
+          header_cells[2].text = 'Desc'
+          for item in recordset:
+              row_cells = table.add_row().cells
+              row_cells[0].text = str(item.qty)
+              row_cells[1].text = str(item.id)
+              row_cells[2].text = item.desc
 
-    table = document.add_table(rows=1, cols=3)
-    table.style = 'LightShading-Accent1'
-    header_cells = table.rows[0].cells
-    header_cells[0].text = 'Qty'
-    header_cells[1].text = 'Id'
-    header_cells[2].text = 'Desc'
-    for item in recordset:
-        row_cells = table.add_row().cells
-        row_cells[0].text = str(item.qty)
-        row_cells[1].text = str(item.id)
-        row_cells[2].text = item.desc
-    
-    document.add_page_break()
+          document.add_page_break()
 
-    document.save('demo.docx')
+          document.save('demo.docx')
+======  ======================================================================
 
 
 User Guide
@@ -70,6 +72,7 @@ User Guide
    user/api-concepts
    user/styles
    user/tables
+   user/shapes
    user/text
 
 
diff --git a/docs/user/shapes.rst b/docs/user/shapes.rst
@@ -0,0 +1,27 @@
+
+Understanding pictures and other shapes
+=======================================
+
+Conceptually, Word documents have two *layers*, a *text layer* and a *drawing
+layer*. In the text layer, text objects are flowed from left to right and from
+top to bottom, starting a new page when the prior one is filled. In the drawing
+layer, drawing objects, called *shapes*, are placed at arbitrary positions.
+and are sometimes referred to as *floating* shapes.
+
+A picture is a shape that can appear in either the text or drawing layer. When
+it appears in the text layer it is called an *inline shape*, or more
+specifically, an *inline picture*.
+
+Inline shapes are treated like a big text character (a *character glyph*). The
+line height is increased to accomodate the shape and the shape is wrapped to
+a line it will fit on width-wise, just like text. Inserting text in front of it
+will cause it to move to the right. Often, a picture is placed in a paragraph
+by itself, but this is not required. It can have text before and after it in
+the paragraph in which it's placed.
+
+At the time of writing, |docx| only supports inline pictures. Floating pictures
+can be added. If you have an active use case, submit a feature request on the
+issue tracker. The ``Document.add_picture()`` method adds a specified picture
+to the end of the document in a paragraph of its own. However, by digging
+a little deeper into the API you can place text on either side of the picture
+in its paragraph, or both.
diff --git a/docx/api.py b/docx/api.py
@@ -18,7 +18,10 @@
 
 class Document(object):
     """
-    API class representing a Word document.
+    Return a |Document| instance loaded from *docx*, where *docx* can be
+    either a path to a ``.docx`` file (a string) or a file-like object. If
+    *docx* is missing or ``None``, the built-in default document "template"
+    is loaded.
     """
     def __init__(self, docx=None):
         super(Document, self).__init__()
@@ -48,12 +51,12 @@ def inline_shapes(self):
         """
         return self._document_part.inline_shapes
 
-    def save(self, file_):
+    def save(self, path_or_stream):
         """
-        Save this document to *file_*, where *file_* can be either a path to
-        a file (a string) or a file-like object.
+        Save this document to *path_or_stream*, which can be either a path to
+        a filesystem location (a string) or a file-like object.
         """
-        self._package.save(file_)
+        self._package.save(path_or_stream)
 
     @staticmethod
     def _open(docx):
