https://github.com/mherkazandjian/docxsphinx
Generate word documents from sphinx documentation
https://github.com/mherkazandjian/docxsphinx
docx docx-generator microsoft python3 python36 sphinx sphinx-doc word
Last synced: 4 months ago
JSON representation
Generate word documents from sphinx documentation
- Host: GitHub
- URL: https://github.com/mherkazandjian/docxsphinx
- Owner: mherkazandjian
- Created: 2017-07-30T18:26:44.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-11-17T06:04:48.000Z (over 1 year ago)
- Last Synced: 2025-09-22T14:34:23.693Z (9 months ago)
- Topics: docx, docx-generator, microsoft, python3, python36, sphinx, sphinx-doc, word
- Language: Python
- Homepage:
- Size: 589 KB
- Stars: 30
- Watchers: 5
- Forks: 11
- Open Issues: 38
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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