docs: first pass at user guide

LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright © 2013 Steve Canny, https://github.com/scanny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

MANIFEST.in

@@ -0,0 +1,6 @@
+include HISTORY.rst LICENSE README.rst tox.ini
+include tests/*.py
+recursive-include features *
+recursive-include docx/templates *
+recursive-include tests/test_files *
+

docs/_templates/sidebarlinks.html

@@ -0,0 +1,6 @@
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="http://github.com/python-openxml/python-docx">python-docx @ GitHub</a></li>
+  <li><a href="http://pypi.python.org/pypi/python-docx">python-docx @ PyPI</a></li>
+  <li><a href="http://github.com/python-openxml/python-docx/issues">Issue Tracker</a></li>
+</ul>

docs/api/document.rst

@@ -15,4 +15,3 @@ Document objects
 
 .. autoclass:: _Document
    :members:
-

docs/api/shape.rst

@@ -0,0 +1,23 @@
+
+.. _shape_api:
+
+Shape-related objects
+=====================
+
+.. currentmodule:: docx.shape
+
+
+|InlineShape| objects
+---------------------
+
+The ``width`` and ``height`` property of |InlineShape| provide a length object
+that is an instance of |Length|. These instances behave like an int, but also
+have built-in units conversion properties, e.g.::
+
+    >>> inline_shape.height
+    914400
+    >>> inline_shape.height.inches
+    1.0
+
+.. autoclass:: InlineShape
+   :members: height, type, width

docs/api/shared.rst

@@ -0,0 +1,39 @@
+
+.. _shared_api:
+
+Shared classes
+==============
+
+.. currentmodule:: docx.shared
+
+
+Length objects
+--------------
+
+Length values in |docx| are expressed as a standardized |Length| value object.
+|Length| is a subclass of |int|, having all the behavior of an |int|. In
+addition, it has built-in units conversion properties, e.g.::
+
+    >>> inline_shape.height
+    914400
+    >>> inline_shape.height.inches
+    1.0
+
+Length objects are constructed using a selection of convenience constructors,
+allowing values to be expressed in the units most appropriate to the context.
+
+.. autoclass:: Length
+   :members:
+   :member-order: bysource
+
+.. autoclass:: Inches
+   :members:
+
+.. autoclass:: Cm
+   :members:
+
+.. autoclass:: Mm
+   :members:
+
+.. autoclass:: Emu
+   :members:

docs/api/table.rst

@@ -0,0 +1,70 @@
+
+.. _table_api:
+
+Table objects
+================
+
+Table objects are constructed using the ``add_table()`` method on |Document|.
+
+Protocol example::
+
+    table = document.add_table(rows=2, cols=2)
+    top_left_cell = table.cell(0, 0)
+    top_left_cell.text = 'foobar'
+
+    # OR
+
+    table = document.add_table(rows=1, cols=2)
+    table.style = 'LightShading-Accent1'
+    header_cells = table.rows[0].cells
+    header_cells[0].text = 'Qty'
+    header_cells[1].text = 'Desc'
+    for item in items:
+        row_cells = table.rows.add().cells
+        row_cells[0].text = str(item.qty)
+        row_cells[2].text = item.desc
+
+
+.. currentmodule:: docx.table
+
+
+|Table| objects
+---------------
+
+.. autoclass:: Table
+   :members:
+
+
+|_Cell| objects
+------------------------
+
+.. autoclass:: _Cell
+   :members:
+
+
+|_Row| objects
+--------------
+
+.. autoclass:: _Row
+   :members:
+
+
+|_Column| objects
+-----------------
+
+.. autoclass:: _Column
+   :members:
+
+
+|_RowCollection| objects
+------------------------
+
+.. autoclass:: _RowCollection
+   :members:
+
+
+|_ColumnCollection| objects
+---------------------------
+
+.. autoclass:: _ColumnCollection
+   :members:

docs/api/text.rst

@@ -0,0 +1,21 @@
+
+.. _text_api:
+
+Text-related objects
+====================
+
+.. currentmodule:: docx.text
+
+
+|Paragraph| objects
+-------------------
+
+.. autoclass:: Paragraph
+   :members:
+
+
+|Run| objects
+-------------
+
+.. autoclass:: Run
+   :members:

docs/conf.py

@@ -19,7 +19,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('../../python-opc'))
+
+from docx import __version__
+
 
 # -- General configuration ---------------------------------------------------
 
@@ -57,22 +59,40 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.3'
+version = __version__
 # The full version, including alpha/beta/rc tags.
-release = '0.3.0d1'
+release = __version__
 
 # A string of reStructuredText that will be included at the end of every source
 # file that is read. This is the right place to add substitutions that should
 # be available in every file.
 rst_epilog = """
+.. |api-Document| replace:: :class:`docx.api.Document`
+
 .. |_Body| replace:: :class:`_Body`
 
+.. |_Cell| replace:: :class:`_Cell`
+
+.. |_Column| replace:: :class:`_Column`
+
+.. |_ColumnCollection| replace:: :class:`_ColumnCollection`
+
 .. |Document| replace:: :class:`Document`
 
 .. |_Document| replace:: :class:`_Document`
 
+.. |docx| replace:: ``python-docx``
+
+.. |Emu| replace:: :class:`Emu`
+
+.. |InlineShape| replace:: :class:`InlineShape`
+
 .. |InlineShapes| replace:: :class:`InlineShapes`
 
+.. |int| replace:: :class:`int`
+
+.. |Length| replace:: :class:`.Length`
+
 .. |OpcPackage| replace:: :class:`OpcPackage`
 
 .. |Paragraph| replace:: :class:`Paragraph`
@@ -85,9 +105,15 @@
 
 .. |RelationshipCollection| replace:: :class:`_RelationshipCollection`
 
-.. |docx| replace:: ``python-docx``
+.. |_Row| replace:: :class:`_Row`
 
-.. |python-docx| replace:: ``python-docx``
+.. |_RowCollection| replace:: :class:`_RowCollection`
+
+.. |Run| replace:: :class:`Run`
+
+.. |Table| replace:: :class:`Table`
+
+.. |Text| replace:: :class:`Text`
 """
 
 
@@ -162,6 +188,10 @@
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
+html_sidebars = {
+    '**': ['localtoc.html', 'relations.html', 'sidebarlinks.html',
+           'searchbox.html']
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/dev/analysis/features/shapes.rst

@@ -46,6 +46,7 @@ Resources
 
 * `Document Members (Word) on MSDN`_
 * `InlineShape Members (Word) on MSDN`_
+* `InlineShapes Members (Word) on MSDN`_
 * `Shape Members (Word) on MSDN`_
 
 .. _Document Members (Word) on MSDN:
@@ -54,5 +55,8 @@ Resources
 .. _InlineShape Members (Word) on MSDN:
    http://msdn.microsoft.com/en-us/library/office/ff840794.aspx
 
+.. _InlineShapes Members (Word) on MSDN:
+   http://msdn.microsoft.com/en-us/library/office/ff836984.aspx
+
 .. _Shape Members (Word) on MSDN:
    http://msdn.microsoft.com/en-us/library/office/ff195191.aspx