fix: python-openxml#266 miscellaneous doc updates

scanny · scanny · commit e24c77d98ab9 · 2018-08-18T16:55:27.000-07:00
diff --git a/docs/index.rst b/docs/index.rst
@@ -42,16 +42,22 @@ Here's an example of what |docx| can do:
 
                                                 document.add_picture('monty-truth.png', width=Inches(1.25))
 
+                                                records = (
+                                                    (3, '101', 'Spam'),
+                                                    (7, '422', 'Eggs'),
+                                                    (4, '631', 'Spam, spam, eggs, and spam')
+                                                )
+
                                                 table = document.add_table(rows=1, cols=3)
                                                 hdr_cells = table.rows[0].cells
                                                 hdr_cells[0].text = 'Qty'
                                                 hdr_cells[1].text = 'Id'
                                                 hdr_cells[2].text = 'Desc'
-                                                for item in recordset:
+                                                for qty, id, desc in records:
                                                     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
+                                                    row_cells[0].text = str(qty)
+                                                    row_cells[1].text = id
+                                                    row_cells[2].text = desc
 
                                                 document.add_page_break()
 
diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst
@@ -115,9 +115,9 @@ supports indexed access, like a list::
     row.cells[0].text = 'Foo bar to you.'
     row.cells[1].text = 'And a hearty foo bar to you too sir!'
 
-The ``.rows`` and ``.columns`` collections on a table are iterable, so you can
-use them directly in a ``for`` loop. Same with the ``.cells`` sequences on
-a row or column::
+The ``.rows`` and ``.columns`` collections on a table are iterable, so you
+can use them directly in a ``for`` loop. Same with the ``.cells`` sequences
+on a row or column::
 
     for row in table.rows:
         for cell in row.cells:
@@ -137,7 +137,11 @@ This can be very handy for the variable length table scenario we mentioned
 above::
 
     # get table data -------------
-    items = get_things_from_database_or_something()
+    items = (
+        (7, '1024', 'Plush kittens'),
+        (3, '2042', 'Furbees'),
+        (1, '1288', 'French Poodle Collars, Deluxe'),
+    )
 
     # add table ------------------
     table = document.add_table(1, 3)
@@ -229,14 +233,11 @@ thing. You can also apply a style afterward. These two lines are equivalent to
 the one above::
 
     paragraph = document.add_paragraph('Lorem ipsum dolor sit amet.')
-    paragraph.style = 'ListBullet'
+    paragraph.style = 'List Bullet'
 
-The style is specified using its style ID, 'ListBullet' in this example.
-Generally, the style ID is formed by removing the spaces in the style name as
-it appears in the Word user interface (UI). So the style 'List Number 3'
-would be specified as ``'ListNumber3'``. However, note that if you are using
-a localized version of Word, the style ID may be derived from the English
-style name and may not correspond so neatly to its style name in the Word UI.
+The style is specified using its style name, 'List Bullet' in this example.
+Generally, the style name is exactly as it appears in the Word user interface
+(UI).
 
 
 Applying bold and italic
@@ -324,8 +325,4 @@ the same result as the lines above::
     run = paragraph.add_run('text with emphasis.')
     run.style = 'Emphasis'
 
-As with a paragraph style, the style ID is formed by removing the spaces in
-the name as it appears in the Word UI. So the style 'Subtle Emphasis' would
-be specified as ``'SubtleEmphasis'``. Note that if you are using
-a localized version of Word, the style ID may be derived from the English
-style name and may not correspond to its style name in the Word UI.
+As with a paragraph style, the style name is as it appears in the Word UI.
diff --git a/docx/styles/styles.py b/docx/styles/styles.py
@@ -51,7 +51,7 @@ def __getitem__(self, key):
                 'style lookup by style_id is deprecated. Use style name as '
                 'key instead.'
             )
-            warn(msg, UserWarning)
+            warn(msg, UserWarning, stacklevel=2)
             return StyleFactory(style_elm)
 
         raise KeyError("no style with name '%s'" % key)

Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,7 @@ def __getitem__(self, key):`
`51`	`51`	`'style lookup by style_id is deprecated. Use style name as '`
`52`	`52`	`'key instead.'`
`53`	`53`	`)`
`54`		`- warn(msg, UserWarning)`
	`54`	`+ warn(msg, UserWarning, stacklevel=2)`
`55`	`55`	`return StyleFactory(style_elm)`
`56`	`56`
`57`	`57`	`raise KeyError("no style with name '%s'" % key)`