Skip to content

Commit d04bbd0

Browse files
author
Steve Canny
committed
docs: document bold/italic feature analysis
Also other miscellaneous documentation fixups
1 parent 1cc66bf commit d04bbd0

File tree

6 files changed

+208
-13
lines changed

6 files changed

+208
-13
lines changed

‎docs/api/shape.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,16 @@
44
Shape-related objects
55
=====================
66

7+
.. currentmodule:: docx.parts.document
8+
9+
10+
|InlineShapes| objects
11+
----------------------
12+
13+
.. autoclass:: InlineShapes
14+
:members:
15+
16+
717
.. currentmodule:: docx.shape
818

919

‎docs/conf.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -81,23 +81,23 @@
8181
8282
.. |docx| replace:: ``python-docx``
8383
84-
.. |Emu| replace:: :class:`Emu`
84+
.. |Emu| replace:: :class:`.Emu`
8585
86-
.. |InlineShape| replace:: :class:`InlineShape`
86+
.. |InlineShape| replace:: :class:`.InlineShape`
8787
88-
.. |InlineShapes| replace:: :class:`InlineShapes`
88+
.. |InlineShapes| replace:: :class:`.InlineShapes`
8989
9090
.. |int| replace:: :class:`int`
9191
9292
.. |Length| replace:: :class:`.Length`
9393
9494
.. |OpcPackage| replace:: :class:`OpcPackage`
9595
96-
.. |Paragraph| replace:: :class:`Paragraph`
96+
.. |None| replace:: ``None``
9797
98-
.. |Part| replace:: :class:`Part`
98+
.. |Paragraph| replace:: :class:`.Paragraph`
9999
100-
.. |Presentation| replace:: :class:`Presentation`
100+
.. |Part| replace:: :class:`Part`
101101
102102
.. |_Relationship| replace:: :class:`_Relationship`
103103
@@ -109,7 +109,7 @@
109109
110110
.. |Run| replace:: :class:`Run`
111111
112-
.. |Table| replace:: :class:`Table`
112+
.. |Table| replace:: :class:`.Table`
113113
114114
.. |Text| replace:: :class:`Text`
115115

‎docs/dev/analysis/features/run-properties.rst‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
2+
Run-properties
3+
==============
4+
5+
Character formatting such as font typeface, size, bold, and italic are applied
6+
at the run level.
7+
8+
9+
Candidate protocol
10+
------------------
11+
12+
The following interactive session demonstrates the protocol for querying and
13+
applying run-level properties::
14+
15+
>>> run = p.add_run()
16+
>>> run.bold
17+
None
18+
>>> run.bold = True
19+
>>> run.bold
20+
True
21+
>>> run.bold = False
22+
>>> run.bold
23+
False
24+
>>> run.bold = None
25+
>>> run.bold
26+
None
27+
28+
29+
Acceptance tests
30+
----------------
31+
32+
::
33+
34+
Feature: Apply bold or italic to run
35+
In order to apply emphasis to a particular word or phrase in a paragraph
36+
As a python-docx developer
37+
I need a way to query and set bold and italic on a run
38+
39+
Scenario: Apply bold to a run
40+
Given a run
41+
When I assign True to its bold property
42+
Then the run appears in bold typeface
43+
44+
Scenario: Remove bold from a run
45+
Given a run having bold set on
46+
When I assign None to its bold property
47+
Then the run appears with its inherited bold setting
48+
49+
Scenario: Set bold off unconditionally
50+
Given a run
51+
When I assign False to its bold property
52+
Then the run appears without bold regardless of its style hierarchy
53+
54+
55+
Specimen XML
56+
------------
57+
58+
.. highlight:: xml
59+
60+
::
61+
62+
<w:r w:rsidRPr="00FA3070">
63+
<w:rPr>
64+
<w:b/>
65+
<w:i/>
66+
<w:smallCaps/>
67+
<w:strike/>
68+
<w:sz w:val="28"/>
69+
<w:szCs w:val="28"/>
70+
<w:u w:val="single"/>
71+
</w:rPr>
72+
<w:t>bold, italic, small caps, strike, size, and underline, applied in
73+
reverse order but not to paragraph mark</w:t>
74+
</w:r>
75+
76+
77+
Schema excerpt
78+
--------------
79+
80+
.. highlight:: xml
81+
82+
It appears the run properties may appear in any order and may appear multiple
83+
times each. Not sure what the semantics of that would be or why one would
84+
want to do it, but something to note. Word seems to place them in the order
85+
below when it writes the file.::
86+
87+
<xsd:complexType name="CT_R"> <!-- denormalized -->
88+
<xsd:sequence>
89+
<xsd:element name="rPr" type="CT_RPr" minOccurs="0"/>
90+
<xsd:group ref="EG_RunInnerContent" minOccurs="0" maxOccurs="unbounded"/>
91+
</xsd:sequence>
92+
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
93+
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
94+
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
95+
</xsd:complexType>
96+
97+
<xsd:complexType name="CT_RPr">
98+
<xsd:sequence>
99+
<xsd:group ref="EG_RPrContent" minOccurs="0"/>
100+
</xsd:sequence>
101+
</xsd:complexType>
102+
103+
<xsd:group name="EG_RPrContent">
104+
<xsd:sequence>
105+
<xsd:group ref="EG_RPrBase" minOccurs="0" maxOccurs="unbounded"/>
106+
<xsd:element name="rPrChange" type="CT_RPrChange" minOccurs="0"/>
107+
</xsd:sequence>
108+
</xsd:group>
109+
110+
<xsd:group name="EG_RPrBase">
111+
<xsd:choice>
112+
<xsd:element name="rStyle" type="CT_String"/>
113+
<xsd:element name="rFonts" type="CT_Fonts"/>
114+
<xsd:element name="b" type="CT_OnOff"/>
115+
<xsd:element name="bCs" type="CT_OnOff"/>
116+
<xsd:element name="i" type="CT_OnOff"/>
117+
<xsd:element name="iCs" type="CT_OnOff"/>
118+
<xsd:element name="caps" type="CT_OnOff"/>
119+
<xsd:element name="smallCaps" type="CT_OnOff"/>
120+
<xsd:element name="strike" type="CT_OnOff"/>
121+
<xsd:element name="dstrike" type="CT_OnOff"/>
122+
<xsd:element name="outline" type="CT_OnOff"/>
123+
<xsd:element name="shadow" type="CT_OnOff"/>
124+
<xsd:element name="emboss" type="CT_OnOff"/>
125+
<xsd:element name="imprint" type="CT_OnOff"/>
126+
<xsd:element name="noProof" type="CT_OnOff"/>
127+
<xsd:element name="snapToGrid" type="CT_OnOff"/>
128+
<xsd:element name="vanish" type="CT_OnOff"/>
129+
<xsd:element name="webHidden" type="CT_OnOff"/>
130+
<xsd:element name="color" type="CT_Color"/>
131+
<xsd:element name="spacing" type="CT_SignedTwipsMeasure"/>
132+
<xsd:element name="w" type="CT_TextScale"/>
133+
<xsd:element name="kern" type="CT_HpsMeasure"/>
134+
<xsd:element name="position" type="CT_SignedHpsMeasure"/>
135+
<xsd:element name="sz" type="CT_HpsMeasure"/>
136+
<xsd:element name="szCs" type="CT_HpsMeasure"/>
137+
<xsd:element name="highlight" type="CT_Highlight"/>
138+
<xsd:element name="u" type="CT_Underline"/>
139+
<xsd:element name="effect" type="CT_TextEffect"/>
140+
<xsd:element name="bdr" type="CT_Border"/>
141+
<xsd:element name="shd" type="CT_Shd"/>
142+
<xsd:element name="fitText" type="CT_FitText"/>
143+
<xsd:element name="vertAlign" type="CT_VerticalAlignRun"/>
144+
<xsd:element name="rtl" type="CT_OnOff"/>
145+
<xsd:element name="cs" type="CT_OnOff"/>
146+
<xsd:element name="em" type="CT_Em"/>
147+
<xsd:element name="lang" type="CT_Language"/>
148+
<xsd:element name="eastAsianLayout" type="CT_EastAsianLayout"/>
149+
<xsd:element name="specVanish" type="CT_OnOff"/>
150+
<xsd:element name="oMath" type="CT_OnOff"/>
151+
</xsd:choice>
152+
</xsd:group>
153+
154+
<xsd:complexType name="CT_OnOff">
155+
<xsd:attribute name="val" type="s:ST_OnOff"/>
156+
</xsd:complexType>
157+
158+
<xsd:simpleType name="ST_OnOff">
159+
<xsd:union memberTypes="xsd:boolean ST_OnOff1"/>
160+
</xsd:simpleType>
161+
162+
<xsd:simpleType name="ST_OnOff1">
163+
<xsd:restriction base="xsd:string">
164+
<xsd:enumeration value="on"/>
165+
<xsd:enumeration value="off"/>
166+
</xsd:restriction>
167+
</xsd:simpleType>
168+
169+
170+
Resources
171+
---------
172+
173+
* `WdBreakType Enumeration on MSDN`_
174+
* `Range.InsertBreak Method (Word) on MSDN`_
175+
176+
.. _WdBreakType Enumeration on MSDN:
177+
http://msdn.microsoft.com/en-us/library/office/ff195905.aspx
178+
179+
.. _Range.InsertBreak Method (Word) on MSDN:
180+
http://msdn.microsoft.com/en-us/library/office/ff835132.aspx

‎docs/dev/analysis/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Feature Analysis
1717
features/shapes-inline
1818
features/shapes-inline-size
1919
features/picture
20+
features/run-properties
2021

2122

2223
Schema Analysis

‎docs/index.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,9 @@ Here's an example of what |docx| can do:
4343

4444
document.add_picture('monty-truth.png')
4545

46-
table = document.add_table(rows=1, cols=3)
47-
table.style = 'LightShading-Accent1'
46+
table = document.add_table(
47+
rows=1, cols=3, table.style='LightShading-Accent1'
48+
)
4849
header_cells = table.rows[0].cells
4950
header_cells[0].text = 'Qty'
5051
header_cells[1].text = 'Id'

‎docx/shape.py‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@ def __init__(self, inline):
2626
@property
2727
def height(self):
2828
"""
29-
Return the display height of this inline shape as an |Emu| instance.
29+
Read/write. The display height of this inline shape as an |Emu|
30+
instance.
3031
"""
3132
return self._inline.extent.cy
3233

@@ -55,8 +56,9 @@ def new_picture(cls, r, image_part, rId, shape_id):
5556
@property
5657
def type(self):
5758
"""
58-
Return the member of ``docx.enum.shape.WD_INLINE_SHAPE`` denoting the
59-
inline shape type, e.g. ``LINKED_PICTURE``.
59+
The type of this inline shape as a member of
60+
``docx.enum.shape.WD_INLINE_SHAPE``, e.g. ``LINKED_PICTURE``.
61+
Read-only.
6062
"""
6163
graphicData = self._inline.graphic.graphicData
6264
uri = graphicData.uri
@@ -74,7 +76,8 @@ def type(self):
7476
@property
7577
def width(self):
7678
"""
77-
Return the display width of this inline shape as an |Emu| instance.
79+
Read/write. The display width of this inline shape as an |Emu|
80+
instance.
7881
"""
7982
return self._inline.extent.cx
8083

0 commit comments

Comments
 (0)