docxsphinx 1.0.0

Sphinx docx builder extension.

# DocxSphinx

[](https://circleci.com/gh/mherkazandjian/docxsphinx/tree/master)

Introduction

This repository has been forked from

https://bitbucket.org/shimizukawa/sphinxcontrib-docxbuilder

and some heavy modification have been done. The major changes are listed in the release notes (todo add the release notes).

Installation

The latest bleeding edge version can be installed through

` pip install docxsphinx `

To install the development version

` pip install git+https://github.com/mherkazandjian/docxsphinx.git@master `

Alternatively the repository can be cloned and installed locally

` git clone https://github.com/mherkazandjian/docxsphinx.git cd docxsphinx python -m pip install -r requirements.txt python setup.py install `

After installation, `make docx` in a sphinx project should work (see next section)

Generating a docx document

It is assumed that a sphinx project already is in place. At least one change must be done to conf.py in-order to be able to generate a docx file.

The following line must be added to conf.py:

` extensions = ['docxsphinx'] `

The sample projects are in the directory examples

• REPO_ROOT/examples/sample_1 : default example (from the original repo)

• REPO_ROOT/examples/sample_2 : example tested with make docx

• REPO_ROOT/examples/sample_3 : example tested with make docx with a custom style

Word styles

a custom word style file can be specified by adding

` # 'docx_template' need *.docx or *.dotx template file name. default is None. docx_template = 'template.docx' `

to the end of conf.py (or anywhere in the file)

Development

Setup the development environment (make sure that pipenv is installed):

` pipenv install --dev # creates the .venv dir pipenv shell # set the environment to use the venv python setup.py install make tests -B `

whenever changes are made the package needs to be re-installed through:

` python setup.py install `

since the tests are run using the commands sphinx-build that needs to be in the environment paths.

The tests can also be run using (but this is not recommended and will be removed in the future):

` python setup.py test `

To debug the build process

` python -m pdb $(which sphinx-build) -b docx /path/to/src/dir /path/to/build/dir OTHER_SPHINX_OPTIONS_IF_ANY `

To produce the .docx of any of the example files using the current development docxsphinx source, e.g. the sphixn project sample_2:

` cd examples/sample_2 PYTHONPATH=../../src:$PYTHONPATH make docx -B `

Profiling is useful to see which sections of the code are visited in the module src/docxsphinx/writer.py. For example to profile sample_2, the following pattern can be used:

` PYTHONPATH=../../src:$PYTHONPATH python3 -m cProfile -s calls $(which sphinx-build) -M docx source build/docx/ | grep writer.py | awk '{print $6}' | sort > calls `

API

see also

REPO_ROOT/src/README.md (outdated - but useful) REPO_ROOT/src/docxsphinx/docx/README.md