Clone wiki

sphinx-docxbuilder / Home

Welcome Sphinx-docxbuilder

<Japanese page>

What is sphinx-docbuilder

This is a sphinx docx builder extension. This extension is developed by hacking 'sphinxcontrib-docxbuilder'.

This extension use a docx composer module for the docx file generation. The module is developed by hacking 'python-docx' module.

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'

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 works followings:

  • Headings
  • Bullet List
  • Enumerated Lists
  • Definition Lists
  • Field Lists (simple text only)
  • Literal Blocks (no colors)
  • Line Blocks
  • Block Quotes
  • Option Lists (simple text only)
  • Simple table and csv table
  • Images
  • Admonitions
  • High Lighting in literal blocks
  • Basic Inline Markups

Known issue

Many sphinx syntax and directives aren't test yet.

Information

  • Keywords: sphinx,extension,builder,docx,OpenXML
  • License: MIT

Updated