An extension for a docx file generation with Sphinx-1.1.2
Copyright(c) 2011, haraisao at gmail dot com
This programs is an extension to generate a docx file with Sphinx-1.1.2. This extension is developed by hacking both 'sphinxcontrib-docxbuilder' and 'python-docx'.
Special thanks to Mike MacCana and Takayuki SHIMIZUKAWA.
Auther: Isao Hara Home Page: https://bitbucket.org/haraisao/sphinx-docxbuilder/ Keywords: sphinx,extension,builder,docx,OpenXML License: MIT
This program is consist of following files.
- builder.py This file defined a builder class for Sphinx-1.1.2. This file is copyed from sphinx-docxbuilder's one.
- writer.py This file defined a writer class for Sphinx-1.1.2. This file is modified sphinx-docxbuilder's.
- highlight.py This file defined DocxFormatter and DocxPygmentsBridge to support highlighting in the literal block.
- docx/docx.py This file defined two classes to manipulate a docx file.
- docx/style.docx This is a default style file. If you customize a docx document when you generate sphinx-docxbuilder, please copy this file in a local directory and modify styles with MS Word.
- contrib/quickstart.py This is for 'sphinx-quickstart' command to add some definitions for 'sphinx-docxbuilder'. Please replace the original one.
- contrib/exportDocx.py contrib/restructDocx.py These are sample command to export/restruct docx file.
- Python2.6 or later
- lxml module
- PIL(Python Imaging Library) module
- Optionally, you need MS Word 2007 or later to modify a style file.
Currently it works followings:
- Bullet List
- Enumerated Lists
- Definition Lists
- Field Lists (simple text only)
- Literal Blocks
- High Lighing in Literal Blocks
- Line Blocks
- Block Quotes
- Option Lists (simple text only)
- Simple table and csv table
- Basic Inline Markups
Many sphinx syntaxes and directives aren't tested yet.
First of all, download or hg clone sphix-docxbuilder archive and extract all files into $(SPHINX_EGG_DIR)/sphinx-docxbuilder . Usage
Set 'sphinx-docxbuilder' to 'extensions' line of target sphinx source conf.py
extensions = ['sphinx-docxbuilder']
Execute sphinx-build with below option
$ sphinx-build -b docx [input-dir] [output-dir]
Customize Style file
If you want to customize output file, only you have to do is to change named styles in 'sphinx-doc/docx/style.docx' .
Customize document properties
sphinx-docxbuilder support to customize document properties. Currently, you can set 'title','subject','creator','company','category','descriptions','keyword' to append expressions to 'conf.py'.
For example, to set the creator and the keyword properties, you add follows
docx_creator = 'Isao HARA' docx_keywords = ['Sphinx', 'OpenXML']
Futhermore, you can use your original style file to set following expressions to 'conf.py'.
docx_style = 'MyStyle.docx'