Skip to content

Commit 629cadb

Browse files
author
Steve Canny
committed
docs: first pass at user guide
1 parent e386299 commit 629cadb

File tree

27 files changed

+557
-235
lines changed

27 files changed

+557
-235
lines changed

‎LICENSE‎

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

‎MANIFEST.in‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
include HISTORY.rst LICENSE README.rst tox.ini
2+
include tests/*.py
3+
recursive-include features *
4+
recursive-include docx/templates *
5+
recursive-include tests/test_files *
6+

‎docs/_static/img/example-docx-01.png‎

87 KB
Loading

‎docs/_templates/sidebarlinks.html‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<h3>Useful Links</h3>
2+
<ul>
3+
<li><a href="http://github.com/python-openxml/python-docx">python-docx @ GitHub</a></li>
4+
<li><a href="http://pypi.python.org/pypi/python-docx">python-docx @ PyPI</a></li>
5+
<li><a href="http://github.com/python-openxml/python-docx/issues">Issue Tracker</a></li>
6+
</ul>

‎docs/api/document.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,3 @@ Document objects
1515

1616
.. autoclass:: _Document
1717
:members:
18-

‎docs/api/shape.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
.. _shape_api:
3+
4+
Shape-related objects
5+
=====================
6+
7+
.. currentmodule:: docx.shape
8+
9+
10+
|InlineShape| objects
11+
---------------------
12+
13+
The ``width`` and ``height`` property of |InlineShape| provide a length object
14+
that is an instance of |Length|. These instances behave like an int, but also
15+
have built-in units conversion properties, e.g.::
16+
17+
>>> inline_shape.height
18+
914400
19+
>>> inline_shape.height.inches
20+
1.0
21+
22+
.. autoclass:: InlineShape
23+
:members: height, type, width

‎docs/api/shared.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
2+
.. _shared_api:
3+
4+
Shared classes
5+
==============
6+
7+
.. currentmodule:: docx.shared
8+
9+
10+
Length objects
11+
--------------
12+
13+
Length values in |docx| are expressed as a standardized |Length| value object.
14+
|Length| is a subclass of |int|, having all the behavior of an |int|. In
15+
addition, it has built-in units conversion properties, e.g.::
16+
17+
>>> inline_shape.height
18+
914400
19+
>>> inline_shape.height.inches
20+
1.0
21+
22+
Length objects are constructed using a selection of convenience constructors,
23+
allowing values to be expressed in the units most appropriate to the context.
24+
25+
.. autoclass:: Length
26+
:members:
27+
:member-order: bysource
28+
29+
.. autoclass:: Inches
30+
:members:
31+
32+
.. autoclass:: Cm
33+
:members:
34+
35+
.. autoclass:: Mm
36+
:members:
37+
38+
.. autoclass:: Emu
39+
:members:

‎docs/api/table.rst‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
2+
.. _table_api:
3+
4+
Table objects
5+
================
6+
7+
Table objects are constructed using the ``add_table()`` method on |Document|.
8+
9+
Protocol example::
10+
11+
table = document.add_table(rows=2, cols=2)
12+
top_left_cell = table.cell(0, 0)
13+
top_left_cell.text = 'foobar'
14+
15+
# OR
16+
17+
table = document.add_table(rows=1, cols=2)
18+
table.style = 'LightShading-Accent1'
19+
header_cells = table.rows[0].cells
20+
header_cells[0].text = 'Qty'
21+
header_cells[1].text = 'Desc'
22+
for item in items:
23+
row_cells = table.rows.add().cells
24+
row_cells[0].text = str(item.qty)
25+
row_cells[2].text = item.desc
26+
27+
28+
.. currentmodule:: docx.table
29+
30+
31+
|Table| objects
32+
---------------
33+
34+
.. autoclass:: Table
35+
:members:
36+
37+
38+
|_Cell| objects
39+
------------------------
40+
41+
.. autoclass:: _Cell
42+
:members:
43+
44+
45+
|_Row| objects
46+
--------------
47+
48+
.. autoclass:: _Row
49+
:members:
50+
51+
52+
|_Column| objects
53+
-----------------
54+
55+
.. autoclass:: _Column
56+
:members:
57+
58+
59+
|_RowCollection| objects
60+
------------------------
61+
62+
.. autoclass:: _RowCollection
63+
:members:
64+
65+
66+
|_ColumnCollection| objects
67+
---------------------------
68+
69+
.. autoclass:: _ColumnCollection
70+
:members:

‎docs/api/text.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
2+
.. _text_api:
3+
4+
Text-related objects
5+
====================
6+
7+
.. currentmodule:: docx.text
8+
9+
10+
|Paragraph| objects
11+
-------------------
12+
13+
.. autoclass:: Paragraph
14+
:members:
15+
16+
17+
|Run| objects
18+
-------------
19+
20+
.. autoclass:: Run
21+
:members:

‎docs/conf.py‎

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@
1919
# add these directories to sys.path here. If the directory is relative to the
2020
# documentation root, use os.path.abspath to make it absolute, like shown here.
2121
sys.path.insert(0, os.path.abspath('..'))
22-
sys.path.insert(0, os.path.abspath('../../python-opc'))
22+
23+
from docx import __version__
24+
2325

2426
# -- General configuration ---------------------------------------------------
2527

@@ -57,22 +59,40 @@
5759
# built documents.
5860
#
5961
# The short X.Y version.
60-
version = '0.3'
62+
version = __version__
6163
# The full version, including alpha/beta/rc tags.
62-
release = '0.3.0d1'
64+
release = __version__
6365

6466
# A string of reStructuredText that will be included at the end of every source
6567
# file that is read. This is the right place to add substitutions that should
6668
# be available in every file.
6769
rst_epilog = """
70+
.. |api-Document| replace:: :class:`docx.api.Document`
71+
6872
.. |_Body| replace:: :class:`_Body`
6973
74+
.. |_Cell| replace:: :class:`_Cell`
75+
76+
.. |_Column| replace:: :class:`_Column`
77+
78+
.. |_ColumnCollection| replace:: :class:`_ColumnCollection`
79+
7080
.. |Document| replace:: :class:`Document`
7181
7282
.. |_Document| replace:: :class:`_Document`
7383
84+
.. |docx| replace:: ``python-docx``
85+
86+
.. |Emu| replace:: :class:`Emu`
87+
88+
.. |InlineShape| replace:: :class:`InlineShape`
89+
7490
.. |InlineShapes| replace:: :class:`InlineShapes`
7591
92+
.. |int| replace:: :class:`int`
93+
94+
.. |Length| replace:: :class:`.Length`
95+
7696
.. |OpcPackage| replace:: :class:`OpcPackage`
7797
7898
.. |Paragraph| replace:: :class:`Paragraph`
@@ -85,9 +105,15 @@
85105
86106
.. |RelationshipCollection| replace:: :class:`_RelationshipCollection`
87107
88-
.. |docx| replace:: ``python-docx``
108+
.. |_Row| replace:: :class:`_Row`
89109
90-
.. |python-docx| replace:: ``python-docx``
110+
.. |_RowCollection| replace:: :class:`_RowCollection`
111+
112+
.. |Run| replace:: :class:`Run`
113+
114+
.. |Table| replace:: :class:`Table`
115+
116+
.. |Text| replace:: :class:`Text`
91117
"""
92118

93119

@@ -162,6 +188,10 @@
162188

163189
# Custom sidebar templates, maps document names to template names.
164190
#html_sidebars = {}
191+
html_sidebars = {
192+
'**': ['localtoc.html', 'relations.html', 'sidebarlinks.html',
193+
'searchbox.html']
194+
}
165195

166196
# Additional templates that should be rendered to pages, maps page names to
167197
# template names.

0 commit comments

Comments
 (0)