sphinxcontrib-docxbuilder 0.0.1alpha

Sphinx docx builder extension.

Sphinx docx builder extension generate single docx file from Sphinx document source. This extension use python-docx module (included) for the docx file generation.

Features

• This extension work on Multi-platform (not need OpenOffice or MS Word).

• Usable sphinx syntax and directives:

  • heading line output

  • paragraph output (standard body text)

  • image and figure directive output

  • bullet-list and numbered-list output

  • table output (restrictive)

Currently, many directives and indented block are not work correctly, yet.

Setup

Make environment by easy_install

Not yet.

Make environment by buildout

‘hg clone’ or download sphinxcontrib-docxbuilder archive from ‘get source’ menu at http://bitbucket.org/shimizukawa/sphinxcontrib-docxbuilder

$ cd /path/to/sphinxcontrib-docxbuilder
$ python bootstrap.py -d init
$ bin/buildout

run example

for example sphinx-docx building, simply run below:

$ bin/example
...
Saved new file to: examples/example-0.1.docx

Usage

Set ‘sphinxcontrib-docxbuilder’ to ‘extensions’ line of target sphinx source conf.py:

extensions = ['sphinxcontrib-docxbuilder']

Execute sphinx-build with below option:

$ bin/sphinx-build -b docx [input-dir] [output-dir]
$ ls [output-dir]
output.docx

Requirements

• Python 2.6 or later (not support 3.x)

• python-docx (not released, but included), Thanks Mike MacCana.

• setuptools or distriubte.

History

0.0.1 (unreleased)

• Not released.

Todos

Functionals

• table output

• toctree generation (dispose toctree output? create by docx function?)

• reset number for non-continuous numbered list

• add page-break directive

• implement many many directives

  • note

  • warning

  • code highlighting

  • and etc….

• using dotx template

• some emphasis (italic, bold)

Environments

• docx builder need python-docx package, but not distributed at PyPI.

• python-docx can’t generate <w:i> (italic) and <w:b> (bold) mode tag.

Known Issues

• some indented block output are not working correctly yet.

  • block-quote

  • literal-block

• figure directive’s caption become normal paragraph (not bundled with image).

• python-docx using template’s media(image) folder for temporarily, then some independent document’s media files are shared unexpectly.

• image directive break docx format (maybe very large file are included)