Skip to main content

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

Project description


===============================================================
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'





Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page