sphinx-docx 1.0.0

SVG images

Use .. image:: or .. figure:: with an .svg file, as with any other image:

.. image:: diagram.svg
   :width: 12cm

Each SVG is embedded twice: the vector original, which Word 2016 and later draw sharp at any zoom, and a png rendered with cairosvg for older clients.

Sizing follows the SVG’s own width and height in any absolute unit (px, pt, pc, in, cm, mm), falling back to the viewBox when they are missing or relative. :width: and :height: override that as usual.

cairosvg is installed as a dependency. Without it the build still succeeds; every SVG is skipped with a warning instead of aborting.

Images an SVG pulls in with an href (another svg, a bitmap) are inlined as data URIs, so they survive the move into the docx. References made through CSS url() are not, and draw empty (#TODO).

CSS custom properties are substituted before either renderer sees the file, because neither cairosvg nor Word implements them. var(--bg, #ffffff) becomes #ffffff; a var() with no fallback takes the value declared for it elsewhere in the file, and one with neither becomes none. Drawio emit these constantly – a recent draw.io SVG is full of them – and without the substitution cairosvg fails the whole image with invalid literal for int() with base 16.

Directives

Beyond what the original builder handles:

Admonitions take one table style per type, not a shared one: .. note:: uses Admonition Note, .. warning:: uses Admonition Warning, and a .. admonition:: My Title uses Admonition My Title. Define the style in your style file to change how that one type looks. Types you do not define get a style created from Based Admonition, so nothing breaks if it is missing.

Code highlighting

:emphasize-lines: highlights a line with the highlight_color of the Pygments style, which is normally a hex string. A common color name is accepted too:

# in conf.py, or a style module on sys.path
from pygments.styles.default import DefaultStyle

class MyStyle(DefaultStyle):
    highlight_color = 'lightgreen'

pygments_style = 'mystyle.MyStyle'

Word does not take a color here: its w:highlight accepts only the fifteen names of the OOXML ST_HighlightColor list, and a file using any other name is invalid. So the requested color is snapped to the nearest name Word does have, matching hue before brightness. lightgreen and lime highlight green, orange and gold yellow, navy dark blue.

Style file

Generated docx file’s design is customized by a style file (The default style is sphinx_docx/docx/style.docx). The style file is a docx file, which defines some paragraph, character, and table styles.

The below lists shows typical styles.

Character styles:

• Emphasis

• Strong

• Literal

• Hyperlink

• Footnote Reference

Paragraph styles:

• Body Text

• Footnote Text

• Definition Term

• Literal Block

• Image Caption, Table Caution, Literal Caption

• Heading 1, Heading 2, …, Heading N

• TOC Heading

• toc 1, toc 2, …, toc N

• List Bullet

• List Number

Table styles:

• Table

• Field List

• Production List

• Admonition, Admonition Note, Admonition Warning, …