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).
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)
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 docxwith a custom style
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)
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
see also
REPO_ROOT/src/README.md (outdated - but useful)
REPO_ROOT/src/docxsphinx/docx/README.md