sphinx-docxbuilder 2019.1.28

An extension for a docx file generation with Sphinx (Fork of https://bitbucket.org/haraisao/sphinx-docxbuilder)

===============================================================
sphinx-docxbuilder

An extension for a docx file generation with Sphinx-1.1.2

Copyright(c) 2011, haraisao at gmail dot com
===============================================================

About this
==========
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.

Information
=============
Auther: Isao Hara
Home Page: https://bitbucket.org/haraisao/sphinx-docxbuilder/
Keywords: sphinx,extension,builder,docx,OpenXML
License: MIT

Files
=====
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.

Requirements
=============
* Python2.6 or later
* lxml module
* PIL(Python Imaging Library) module
* Optionally, you need MS Word 2007 or later to modify a style file.

Features
==========
Currently it works followings:

* Headings
* 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
* Images
* Admonitions
* Basic Inline Markups

Known issue
============
Many sphinx syntaxes and directives aren't tested yet.


Quick Start
=============
Setup
-----
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'