docxgen DocumentationRelease 1.0.3

Kun Xi

Apr 21, 2017

Contents

1 Quickstart 31.1 Key Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Installation 52.1 Installing a released version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Installing the development version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Development 73.1 Types of Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Get Started! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.3 Pull Request Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 API Documentation 114.1 E Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.2 Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114.3 Document Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5 License 135.1 Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135.2 docxgen License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6 Changelog 156.1 Version 0.1.3 (2014-01-20) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Python Module Index 17

i

ii

docxgen Documentation, Release 1.0.3

A library to generate Microsoft Office Word 2007 documents.

Github | Issues | PyPi

This work is proudly sponsored by SurveyMonkey.

Contents 1

docxgen Documentation, Release 1.0.3

2 Contents

CHAPTER 1

Quickstart

So you have some great thoughts in your mind, and you want to save them in a beautiful Microsoft Word document?Here is an example how Moby Dick might be crafted:

1. Import the docxgen library first

>>> from docxgen import *

2. Create a Document instance

>>> doc = Document()

3. Add title, heading, and paragraph in the document body, repeat the following steps until the work isfinished.

>>> body = doc.body>>> body.append(title(run('Moby Dick; or, the whale')))>>> body.append(h1(run('CHAPTER 1. Loomings.')))>>> body.append(paragraph([run('Call me Ishmael. Some years ago ...')]))

4. update the document core properties to claim your authorship.

>>> doc.update(title='Moby Dick; or, the Whale', creator='Herman Melville')

5. Save the document and profit!

>>> doc.save('/tmp/moby-dick.docx')

Key Concepts

The Microsoft Word document is mere a collection of document, stylesheets, image blobs serialized in the zip for-mat. The main document is just a XML file specified as WordprocessingML. So technically, you can create a Worddocument from scratch just using a text editor and zip utility application.

3

docxgen Documentation, Release 1.0.3

docxgen leverages the power of lxml library to provide a more convenient interface to create the Word documentelement than the bare-metal XML manipulation. You do not need to dive into the WordProcessingML spec, but wehighly recommend you to understand some key concepts:

• The smallest build block in the WordprocessingML is a text element, t.

• Then you can attach visual styles, like bold, italic and foreground / background colors to create a text run, r.

• The text runs form a paragraph, para, which may be stylized for heading, title, and various list items.

• All the paragraphs are saved in a body element just like HTML.

• The body is then saved in the top-level element document.

• The document is serialized as word/document.xml with other stylesheets and image blobs into a zipcontainer during the serialization.

Please head over to the API Documentation for more information, also it is worthy checking out the lxml documentfor the convention used in the docxgen.

4 Chapter 1. Quickstart

CHAPTER 2

Installation

docxgen requires python 2.6 and above to work correctly. It also works with python 3.2 or 3.3 thanks to the sixcompatibility layer.

Installing a released version

You can install the most recent docxgen version using easy_install:

sudo easy_install docxgen

Or you can also use pip:

sudo pip install docxgen

Either way we strongly recommend using these tools in combination with virtualenv.

This will install a docxgen egg in your Python installation’s site-packages directory.

Alternatively you can install from the release tarball:

1. Download the most recent tarball from the download page.

2. Unpack the tarball.

3. sudo python setup.py install

Note that the last command will automatically download and install setuptools if you don’t already have it installed.This requires a working Internet connection.

This will install docxgen into your Python installation’s site-packages directory.

Installing the development version

If you prefer to live on the edge, be my guest.

5

docxgen Documentation, Release 1.0.3

1. Install Git

2. git clone git://github.com/kunxi/docxgen.git

3. cd docxgen

4. sudo python setup.py install

6 Chapter 2. Installation

CHAPTER 3

Development

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at https://github.com/kunxi/docxgen/issues.

If you are reporting a bug, please include:

• Your operating system name and version.

• Any details about your local setup that might be helpful in troubleshooting.

• Detailed steps to reproduce the bug.

Fix Bugs

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.

Implement Features

Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implementit.

7

docxgen Documentation, Release 1.0.3

Write Documentation

docxgen could always use more documentation, whether as part of the official docxgen docs, in docstrings, or even onthe web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/kunxi/docxgen/issues.

If you are proposing a feature:

• Explain in detail how it would work.

• Keep the scope as narrow as possible, to make it easier to implement.

• Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up docxgen for local development.

1. Fork the docxgen repo on GitHub.

2. Clone your fork locally:

$ git clone git@github.com:your_name_here/docxgen.git

3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set upyour fork for local development:

$ mkvirtualenv docxgen$ cd docxgen/$ python setup.py develop

4. Create a branch for local development:

$ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing otherPython versions with tox:

$ flake8 docxgen tests$ nosetests$ tox

To get flake8 and tox, just pip install them into your virtualenv.

6. Commit your changes and push your branch to GitHub:

$ git add .$ git commit -m "Your detailed description of your changes."$ git push origin name-of-your-bugfix-or-feature

7. Submit a pull request through the GitHub website.

8 Chapter 3. Development

docxgen Documentation, Release 1.0.3

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.

2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a functionwith a docstring, and add the feature to the list in README.rst.

3. The pull request should work for Python 2.6, 2.7, 3.2 and 3.3. Check https://travis-ci.org/kunxi/docxgen/pull_requests and make sure that the tests pass for all supported Python versions.

3.3. Pull Request Guidelines 9

docxgen Documentation, Release 1.0.3

10 Chapter 3. Development

CHAPTER 4

API Documentation

The module defines several functions and constants. For parts where docxgen depends on external libraries, wedocument the most important right here and provide links to the canonical documentation.

E Object

docxgen.E

The E object is an instance of the lxml.ElementMaker with appropriate namespace mapping. It is quite easy to createa WordprocessingML element with the approach:

>>> from xml.etree import ElementTree>>> from docxgen import E>>> t = E.t('I have a dream.')>>> ElementTree.tostring(t)'<ns0:t xmlns:ns0="http://schemas.openxmlformats.org/wordprocessingml/2006/main">I→˓have a dream</ns0:t>'

Basic Usage

docxgen.title(runs)Returns a paragraph with Title style for text runs.

docxgen.subtitle(runs)Returns a paragraph with Subtitle style for text runs.

docxgen.h1(runs)Returns a paragraph with Heading1 style for text runs.

docxgen.h2(runs)Returns a paragraph with Heading2 style for text runs.

11

docxgen Documentation, Release 1.0.3

docxgen.h3(runs)Returns a paragraph with Heading3 style for text runs.

Document Object

12 Chapter 4. API Documentation

CHAPTER 5

License

doxcgen is licensed under MIT license. The full license text can be found below (docxgen License).

Authors

docxgen is written and maintained by Kun Xi.

Development Lead

• Kun Xi <kunxi@kunx.org>

docxgen License

Copyright (c) 2013, Kun Xi

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documen-tation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use,copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whomthe Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of theSoftware.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PAR-TICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHTHOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTIONOF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFT-WARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

13

docxgen Documentation, Release 1.0.3

14 Chapter 5. License

CHAPTER 6

Changelog

Here you can see the full list of changes between each docxgen release.

Version 0.1.3 (2014-01-20)

First public release on PyPI.

15

docxgen Documentation, Release 1.0.3

16 Chapter 6. Changelog

Python Module Index

ddocxgen, 11

17

docxgen Documentation, Release 1.0.3

18 Python Module Index

Index

Ddocxgen (module), 11

EE (in module docxgen), 11

Hh1() (in module docxgen), 11h2() (in module docxgen), 11h3() (in module docxgen), 11

Ssubtitle() (in module docxgen), 11

Ttitle() (in module docxgen), 11

19