X Tutup
Skip to content

Commit 46827d0

Browse files
author
Steve Canny
committed
docs: document table feature analysis
1 parent 7161ce7 commit 46827d0

File tree

8 files changed

+362
-33
lines changed

8 files changed

+362
-33
lines changed

‎docs/api/document.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
2+
.. _document_api:
3+
4+
Document objects
5+
================
6+
7+
... things having to do with Document objects ...
8+
9+
10+
.. currentmodule:: docx.api
11+
12+
13+
|_Document| objects
14+
-------------------
15+
16+
.. autoclass:: _Document
17+
:members:
18+

‎docs/conf.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,8 @@
6565
# file that is read. This is the right place to add substitutions that should
6666
# be available in every file.
6767
rst_epilog = """
68+
.. |_Body| replace:: :class:`_Body`
69+
6870
.. |Document| replace:: :class:`Document`
6971
7072
.. |_Document| replace:: :class:`_Document`

‎docs/dev/analysis/features/table.rst‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
2+
Table
3+
=====
4+
5+
6+
Overview
7+
--------
8+
9+
10+
Open questions
11+
--------------
12+
13+
* Where do table styles fit in? Probably best not to count on a particular
14+
table style being present in the package.
15+
16+
* What about ranges? Why is that a good idea?
17+
18+
19+
Candidate Protocol
20+
------------------
21+
22+
::
23+
24+
>>> row_count, col_count = 2, 2
25+
>>> table = body.add_table(row_count, col_count)
26+
>>> cell = table.cell(0, 0)
27+
>>> p = cell.content[0]
28+
>>> p.text = 'foobar'
29+
>>> p = cell.content.add_paragraph('barfoo')
30+
>>> p.text
31+
'barfoo'
32+
33+
34+
Table access protocol
35+
---------------------
36+
37+
::
38+
39+
>>> table = document.tables[idx]
40+
>>> # OR
41+
>>> for block_item in document.content:
42+
... if isinstance(block_item, _Table):
43+
... ..do table-y things..
44+
45+
46+
47+
MS API
48+
------
49+
50+
::
51+
52+
table = Document.Tables.Add(Range, NumRows, NumCols)
53+
cell = table.Cell(row, col)
54+
55+
56+
Specimen XML
57+
------------
58+
59+
.. highlight:: xml
60+
61+
The following XML is generated by Word when inserting a 2x2 table::
62+
63+
<w:tbl>
64+
<w:tblPr>
65+
<w:tblStyle w:val="TableGrid"/>
66+
<w:tblW w:type="auto" w:w="0"/>
67+
<w:tblLook w:firstColumn="1" w:firstRow="1" w:lastColumn="0"
68+
w:lastRow="0" w:noHBand="0" w:noVBand="1" w:val="04A0"/>
69+
</w:tblPr>
70+
<w:tblGrid>
71+
<w:gridCol w:w="4788"/>
72+
<w:gridCol w:w="4788"/>
73+
</w:tblGrid>
74+
<w:tr>
75+
<w:tc/>
76+
<w:tcPr>
77+
<w:tcW w:type="dxa" w:w="4788"/>
78+
</w:tcPr>
79+
<w:p/>
80+
</w:tc>
81+
<w:tc>
82+
<w:tcPr>
83+
<w:tcW w:type="dxa" w:w="4788"/>
84+
</w:tcPr>
85+
<w:p/>
86+
</w:tc>
87+
</w:tr>
88+
<w:tr>
89+
<w:tc>
90+
<w:tcPr>
91+
<w:tcW w:type="dxa" w:w="4788"/>
92+
</w:tcPr>
93+
<w:p/>
94+
</w:tc>
95+
<w:tc>
96+
<w:tcPr>
97+
<w:tcW w:type="dxa" w:w="4788"/>
98+
</w:tcPr>
99+
<w:p/>
100+
</w:tc>
101+
</w:tr>
102+
</w:tbl>
103+
104+
105+
Minimal XML
106+
-----------
107+
108+
.. highlight:: xml
109+
110+
The following is the minimal XML implied by inserting a 2x2 table::
111+
112+
<w:tbl>
113+
<w:tblPr>
114+
<w:tblW w:type="auto" w:w="0"/>
115+
</w:tblPr>
116+
<w:tblGrid>
117+
<w:gridCol/>
118+
<w:gridCol/>
119+
</w:tblGrid>
120+
<w:tr>
121+
<w:tc>
122+
<w:p/>
123+
</w:tc>
124+
<w:tc>
125+
<w:p/>
126+
</w:tc>
127+
</w:tr>
128+
<w:tr>
129+
<w:tc>
130+
<w:p/>
131+
</w:tc>
132+
<w:tc>
133+
<w:p/>
134+
</w:tc>
135+
</w:tr>
136+
</w:tbl>
137+
138+
139+
Schema Definitions
140+
------------------
141+
142+
.. highlight:: xml
143+
144+
::
145+
146+
<xsd:complexType name="CT_Tbl">
147+
<xsd:sequence>
148+
<xsd:group ref="EG_RangeMarkupElements" minOccurs="0" maxOccurs="unbounded"/>
149+
<xsd:element name="tblPr" type="CT_TblPr"/>
150+
<xsd:element name="tblGrid" type="CT_TblGrid"/>
151+
<xsd:group ref="EG_ContentRowContent" minOccurs="0" maxOccurs="unbounded"/>
152+
</xsd:sequence>
153+
</xsd:complexType>
154+
155+
<xsd:complexType name="CT_TblPr">
156+
<xsd:complexContent>
157+
<xsd:extension base="CT_TblPrBase">
158+
<xsd:sequence>
159+
<xsd:element name="tblPrChange" type="CT_TblPrChange" minOccurs="0"/>
160+
</xsd:sequence>
161+
</xsd:extension>
162+
</xsd:complexContent>
163+
</xsd:complexType>
164+
165+
<xsd:complexType name="CT_TblPrBase">
166+
<xsd:sequence>
167+
<xsd:element name="tblStyle" type="CT_String" minOccurs="0"/>
168+
<xsd:element name="tblpPr" type="CT_TblPPr" minOccurs="0" maxOccurs="1"/>
169+
<xsd:element name="tblOverlap" type="CT_TblOverlap" minOccurs="0" maxOccurs="1"/>
170+
<xsd:element name="bidiVisual" type="CT_OnOff" minOccurs="0" maxOccurs="1"/>
171+
<xsd:element name="tblStyleRowBandSize" type="CT_DecimalNumber" minOccurs="0" maxOccurs="1"/>
172+
<xsd:element name="tblStyleColBandSize" type="CT_DecimalNumber" minOccurs="0" maxOccurs="1"/>
173+
<xsd:element name="tblW" type="CT_TblWidth" minOccurs="0" maxOccurs="1"/>
174+
<xsd:element name="jc" type="CT_JcTable" minOccurs="0" maxOccurs="1"/>
175+
<xsd:element name="tblCellSpacing" type="CT_TblWidth" minOccurs="0" maxOccurs="1"/>
176+
<xsd:element name="tblInd" type="CT_TblWidth" minOccurs="0" maxOccurs="1"/>
177+
<xsd:element name="tblBorders" type="CT_TblBorders" minOccurs="0" maxOccurs="1"/>
178+
<xsd:element name="shd" type="CT_Shd" minOccurs="0" maxOccurs="1"/>
179+
<xsd:element name="tblLayout" type="CT_TblLayoutType" minOccurs="0" maxOccurs="1"/>
180+
<xsd:element name="tblCellMar" type="CT_TblCellMar" minOccurs="0" maxOccurs="1"/>
181+
<xsd:element name="tblLook" type="CT_TblLook" minOccurs="0" maxOccurs="1"/>
182+
<xsd:element name="tblCaption" type="CT_String" minOccurs="0" maxOccurs="1"/>
183+
<xsd:element name="tblDescription" type="CT_String" minOccurs="0" maxOccurs="1"/>
184+
</xsd:sequence>
185+
</xsd:complexType>
186+
187+
<xsd:complexType name="CT_TblWidth">
188+
<xsd:attribute name="w" type="ST_MeasurementOrPercent"/>
189+
<xsd:attribute name="type" type="ST_TblWidth"/>
190+
</xsd:complexType>
191+
192+
<xsd:complexType name="CT_TblLook">
193+
<xsd:attribute name="firstRow" type="s:ST_OnOff"/>
194+
<xsd:attribute name="lastRow" type="s:ST_OnOff"/>
195+
<xsd:attribute name="firstColumn" type="s:ST_OnOff"/>
196+
<xsd:attribute name="lastColumn" type="s:ST_OnOff"/>
197+
<xsd:attribute name="noHBand" type="s:ST_OnOff"/>
198+
<xsd:attribute name="noVBand" type="s:ST_OnOff"/>
199+
<xsd:attribute name="val" type="ST_ShortHexNumber"/>
200+
</xsd:complexType>
201+
202+
<xsd:complexType name="CT_TblGrid">
203+
<xsd:complexContent>
204+
<xsd:extension base="CT_TblGridBase">
205+
<xsd:sequence>
206+
<xsd:element name="tblGridChange" type="CT_TblGridChange" minOccurs="0"/>
207+
</xsd:sequence>
208+
</xsd:extension>
209+
</xsd:complexContent>
210+
</xsd:complexType>
211+
212+
<xsd:complexType name="CT_TblGridBase">
213+
<xsd:sequence>
214+
<xsd:element name="gridCol" type="CT_TblGridCol" minOccurs="0" maxOccurs="unbounded"/>
215+
</xsd:sequence>
216+
</xsd:complexType>
217+
218+
<xsd:complexType name="CT_TblGridCol">
219+
<xsd:attribute name="w" type="s:ST_TwipsMeasure"/>
220+
</xsd:complexType>
221+
222+
<xsd:group name="EG_ContentRowContent">
223+
<xsd:choice>
224+
<xsd:element name="tr" type="CT_Row" minOccurs="0" maxOccurs="unbounded"/>
225+
<xsd:element name="customXml" type="CT_CustomXmlRow"/>
226+
<xsd:element name="sdt" type="CT_SdtRow"/>
227+
<xsd:group ref="EG_RunLevelElts" minOccurs="0" maxOccurs="unbounded"/>
228+
</xsd:choice>
229+
</xsd:group>
230+
231+
<xsd:complexType name="CT_Row">
232+
<xsd:sequence>
233+
<xsd:element name="tblPrEx" type="CT_TblPrEx" minOccurs="0" maxOccurs="1"/>
234+
<xsd:element name="trPr" type="CT_TrPr" minOccurs="0" maxOccurs="1"/>
235+
<xsd:group ref="EG_ContentCellContent" minOccurs="0" maxOccurs="unbounded"/>
236+
</xsd:sequence>
237+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
238+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
239+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
240+
<xsd:attribute name="rsidTr" type="ST_LongHexNumber"/>
241+
</xsd:complexType>
242+
243+
<xsd:group name="EG_ContentCellContent">
244+
<xsd:choice>
245+
<xsd:element name="tc" type="CT_Tc" minOccurs="0" maxOccurs="unbounded"/>
246+
<xsd:element name="customXml" type="CT_CustomXmlCell"/>
247+
<xsd:element name="sdt" type="CT_SdtCell"/>
248+
<xsd:group ref="EG_RunLevelElts" minOccurs="0" maxOccurs="unbounded"/>
249+
</xsd:choice>
250+
</xsd:group>
251+
252+
<xsd:complexType name="CT_Tc">
253+
<xsd:sequence>
254+
<xsd:element name="tcPr" type="CT_TcPr" minOccurs="0" maxOccurs="1"/>
255+
<xsd:group ref="EG_BlockLevelElts" minOccurs="1" maxOccurs="unbounded"/>
256+
</xsd:sequence>
257+
<xsd:attribute name="id" type="s:ST_String" use="optional"/>
258+
</xsd:complexType>
259+
260+
<xsd:group name="EG_BlockLevelElts">
261+
<xsd:choice>
262+
<xsd:group ref="EG_BlockLevelChunkElts" minOccurs="0" maxOccurs="unbounded"/>
263+
<xsd:element name="altChunk" type="CT_AltChunk" minOccurs="0" maxOccurs="unbounded"/>
264+
</xsd:choice>
265+
</xsd:group>
266+
267+
<xsd:group name="EG_BlockLevelChunkElts">
268+
<xsd:choice>
269+
<xsd:group ref="EG_ContentBlockContent" minOccurs="0" maxOccurs="unbounded"/>
270+
</xsd:choice>
271+
</xsd:group>
272+
273+
<xsd:group name="EG_ContentBlockContent">
274+
<xsd:choice>
275+
<xsd:element name="customXml" type="CT_CustomXmlBlock"/>
276+
<xsd:element name="sdt" type="CT_SdtBlock"/>
277+
<xsd:element name="p" type="CT_P" minOccurs="0" maxOccurs="unbounded"/>
278+
<xsd:element name="tbl" type="CT_Tbl" minOccurs="0" maxOccurs="unbounded"/>
279+
<xsd:group ref="EG_RunLevelElts" minOccurs="0" maxOccurs="unbounded"/>
280+
</xsd:choice>
281+
</xsd:group>
282+
283+
284+
Resources
285+
---------
286+
287+
* `Tables.Add Method on MSDN`_
288+
289+
.. _Tables.Add Method on MSDN:
290+
http://msdn.microsoft.com/en-us/library/office/microsoft.office.interop.wo
291+
rd.tables.add(v=office.14).aspx
292+
293+
* `Table Members on MSDN`_
294+
295+
.. _`Table Members on MSDN`:
296+
http://msdn.microsoft.com/en-us/library/office/microsoft.office.interop.wo
297+
od.table_members(v=office.14).aspx

‎docs/dev/analysis/index.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
2+
Analysis
3+
========
4+
5+
Documentation of studies undertaken in support of API and code design.
6+
7+
Feature Analysis
8+
----------------
9+
10+
.. toctree::
11+
:maxdepth: 1
12+
13+
features/table
14+
15+
16+
Schema Analysis
17+
---------------
18+
19+
Collected bits and pieces from the XML Schema docs, MSDN web pages, and the
20+
ISO/IEC 29500 spec.
21+
22+
.. toctree::
23+
:maxdepth: 1
24+
25+
schema/ct_document
26+
schema/ct_body
27+
schema/ct_p
28+
schema/ct_ppr
29+
schema/ct_styles

‎docs/dev/analysis/schema/ct_body.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -90,16 +90,16 @@ Schema excerpt
9090
<xsd:attributeGroup ref="AG_SectPrAttributes"/>
9191
</xsd:complexType>
9292

93-
<xsd:group name="EG_BlockLevelChunkElts">
93+
<xsd:group name="EG_BlockLevelElts">
9494
<xsd:choice>
95-
<xsd:group ref="EG_ContentBlockContent" minOccurs="0" maxOccurs="unbounded"/>
95+
<xsd:group ref="EG_BlockLevelChunkElts" minOccurs="0" maxOccurs="unbounded"/>
96+
<xsd:element name="altChunk" type="CT_AltChunk" minOccurs="0" maxOccurs="unbounded"/>
9697
</xsd:choice>
9798
</xsd:group>
9899

99-
<xsd:group name="EG_BlockLevelElts">
100+
<xsd:group name="EG_BlockLevelChunkElts">
100101
<xsd:choice>
101-
<xsd:group ref="EG_BlockLevelChunkElts" minOccurs="0" maxOccurs="unbounded"/>
102-
<xsd:element name="altChunk" type="CT_AltChunk" minOccurs="0" maxOccurs="unbounded"/>
102+
<xsd:group ref="EG_ContentBlockContent" minOccurs="0" maxOccurs="unbounded"/>
103103
</xsd:choice>
104104
</xsd:group>
105105

‎docs/dev/index.rst‎

Lines changed: 0 additions & 14 deletions
This file was deleted.

0 commit comments

Comments
 (0)
X Tutup