Merge pull request #29 from mherkazandjian/mher/release-1.0.0

Mher/release 1.0.0

MANIFEST.in

@@ -1,7 +1,7 @@
-include buildout.cfg
-include bootstrap.py
 include MANIFEST.in
+include requirements.txt
 recursive-include examples/source *.*
 recursive-include src *.py *.txt
 recursive-include src/docxsphinx/docx *
 
+

Makefile

@@ -6,9 +6,12 @@ testenv:
 	# .. todo:: use pipenv to deploy the installation since sphinx-build expects the plugin to be installed
 	# .. todo:: and it is better not to pollute the actual dev environment
 
-tests:
+tests: clean_tests
 	python setup.py install --force
 	pytest -v tests --tb=no
 
-clean:
+clean_tests:
 	@rm -fvr examples/**/build*
+
+clean: clean_tests
+	@rm -fvr build _build dist *.log .egg*

Pipfile

@@ -0,0 +1,15 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+docutils = "==0.15"
+python-docx = ">=0.8.0"
+Sphinx = ">=3.0.0"
+
+[dev-packages]
+pytest = "==6.1.2"
+
+[requires]
+python_version = "3.6"

README.md

@@ -15,19 +15,24 @@ 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)
@@ -37,12 +42,11 @@ 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 following line must be added to `conf.py`:
 
+   ```
+   extensions = ['docxsphinx']
+   ```
 
 The sample projects are in the directory `examples`
 
@@ -56,30 +60,62 @@ 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
 ===========
-To debug the build process
+
+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
+   ```
 
-    python -m pdb $(which sphinx-build) -b docx /path/to/src/dir /path/to/build/dir OTHER_SPHINX_OPTIONS_IF_ANY
+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
+   ```
+   cd examples/sample_2
+   PYTHONPATH=../../src:$PYTHONPATH make docx -B
+   ```
 
-To profile e.g. ``sample_2``. Profiling is useful to see which sections
-of the code are visited in the module ``src/docxsphinx/writer.py``
+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
+   ```
+   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
 ===

requirements.txt

@@ -1,5 +1,5 @@
 pytest==6.1.2
 docutils==0.15
-sphinx==3.3.0
-python-docx>=0.8.6
-nose==1.3.7
+sphinx>=3.0.0
+python-docx>=0.8.0
+