Metadata-Version: 2.1
Name: docxsphinx
Version: 1.0.0
Summary: Sphinx docx builder extension.
Home-page: https://github.com/mherkazandjian/docxsphinx
Author: Mher Kazandjian, Hugo Buddelmeijer
Author-email: mherkazandjian@gmail.com, hugo@buddelmeijer.nl
License: MIT
Description: # DocxSphinx
        
        [![CircleCI](https://circleci.com/gh/mherkazandjian/docxsphinx/tree/master.svg?style=svg)](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
        
Keywords: sphinx,extension,builder,docx,OpenXML
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Topic :: Office/Business :: Office Suites
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup
Provides-Extra: test
