amedama41 / docxbuilder Goto Github PK

View Code? Open in Web Editor NEW

30.0 7.0 13.0 1.05 MB

Sphinx docx builder extension

Home Page: https://pypi.org/project/docxbuilder/

License: MIT License

Python 99.02% Makefile 0.57% Batchfile 0.41%

sphinx docx-generator sphinx-extension

docxbuilder's Introduction

docxbuilder

Docxbuilder is a Sphinx extension to build docx formatted documents.

Note

This extension is developed based on sphinx-docxbuilder. Though, there is no compatibility between these extensions.

Requirements

Python: 2.7, 3.5 or latter
Sphinx: 1.7.6 or later

Install

Use pip:

pip install docxbuilder

Usage

Add 'docxbuilder' to extensions configuration of conf.py:

extensions = ['docxbuilder']

and build your documents:

make docx

You can control the generated document by adding configurations into conf.py:

docx_documents = [
    ('index', 'docxbuilder.docx', {
         'title': project,
         'creator': author,
         'subject': 'A manual of docxbuilder',
     }, True),
]
docx_style = 'path/to/custom_style.docx'
docx_pagebreak_before_section = 1

For more details, see the documentation.

Style file

Generated docx file's design is customized by a style file (The default style is docxbuilder/docx/style.docx). The style file is a docx file, which defines some paragraph, character, and table styles.

The below lists shows typical styles.

Character styles:

Emphasis
Strong
Literal
Hyperlink
Footnote Reference

Paragraph styles:

Body Text
Footnote Text
Definition Term
Literal Block
Image Caption, Table Caution, Literal Caption
Heading 1, Heading 2, ..., Heading N
TOC Heading
toc 1, toc 2, ..., toc N
List Bullet
List Number

Table styles:

Table
Field List
Admonition Note

TODO

Support math role and directive.
Support tabular_col_spec directive.
Support URL path for images.

Licence

MIT Licence

docxbuilder's People

Stargazers

Watchers

Forkers

steap jinjamator pavlocat theta-dev idahogray joshvazquez tavaresfilipe shel-55 teake laursen79 liberallogic genekong david-le-nir

docxbuilder's Issues

The Literal Block style settings are not applied

Thak you for this extension!

I have a problem with the Literal Block style settings:

Change background color for the Literal Block style in style.docx.
Make DOCX.
Open new DOCX file. Background color is default:

Could you help me please.

Handling images

Hello and thank you for this great project.

At the moment it seems that docxbuilder does not handle images. Is there any workaround ?

Problem ТОС generation

Hi. Very useful extension, but I got the problem with TOC.

In generated docx document there is not any entry in the toc table (except the toc header). I try to update TOC in the Ms Word and got the error 'No table of contents entries found.' with popup (see image)

This say - I have not any title with heading style. But it is incorrect. My document has many headers in their body.

I Use Word for macos

It seems some toc generations error on macos.
If I delete this TOC and generate new one inside MSWord, toc generated correctly.

This is generated docx document

Modified cover page results in IndexError

I copied style.docx to my source directory and I only changed the document title, subject and author in LibreOffice Writer 6.3.2. I saved the file and ran a make docx with a docx_style = 'style.docx' in my conf.py. This results in an exception:

# Sphinx version: 1.8.4
# Python version: 3.6.8 (CPython)
# Docutils version: 0.14
# Jinja2 version: 2.10
# Last messages:
#   processing test.docx...
#
#
#
#   resolving references...
#
#
#
#   writing...
#
# Loaded extensions:
#   sphinx.ext.mathjax (1.8.4) from /usr/local/lib/python3.6/site-packages/sphinx/ext/mathjax.py
#   alabaster (0.7.12) from /usr/local/lib/python3.6/site-packages/alabaster/__init__.py
#   sphinx.ext.todo (1.8.4) from /usr/local/lib/python3.6/site-packages/sphinx/ext/todo.py
#   docxbuilder (unknown version) from /usr/local/lib/python3.6/site-packages/docxbuilder/__init__.py
Traceback (most recent call last):
  File "/usr/local/lib/python3.6/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "/usr/local/lib/python3.6/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 342, in build_update
    self.build(['__all__'], to_build)
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 412, in build
    self.write(docnames, list(updated_docnames), method)
  File "/usr/local/lib/python3.6/site-packages/docxbuilder/builder.py", line 115, in write
    self.write_doc(docname, doctree)
  File "/usr/local/lib/python3.6/site-packages/docxbuilder/builder.py", line 122, in write_doc
    self.writer.write(doctree, destination)
  File "/usr/local/lib/python3.6/site-packages/docutils/writers/__init__.py", line 80, in write
    self.translate()
  File "/usr/local/lib/python3.6/site-packages/docxbuilder/writer.py", line 163, in translate
    visitor = self.builder.create_translator(self.document, self.builder)
  File "/usr/local/lib/python3.6/site-packages/sphinx/builders/__init__.py", line 139, in create_translator                                                                                                       
    return self.app.registry.create_translator(self, *args)
  File "/usr/local/lib/python3.6/site-packages/sphinx/registry.py", line 386, in create_translator
    translator = translator_class(*args)
  File "/usr/local/lib/python3.6/site-packages/docxbuilder/writer.py", line 832, in __init__
    self._bullet_list_id = self._docx.get_bullet_list_num_id('List Bullet')
  File "/usr/local/lib/python3.6/site-packages/docxbuilder/docx/docx.py", line 1458, in get_bullet_list_num_id                                                                                                    
    return self.style_docx.get_numbering_style_id(style_name)
  File "/usr/local/lib/python3.6/site-packages/docxbuilder/docx/docx.py", line 1236, in get_numbering_style_id                                                                                                    
    style_elem, 'w:pPr/w:numPr/w:numId')[0]
IndexError: list index out of range

Any idea what is going on? The document title, subject and author are really the only things I have changed in the style file. When I replace the file by the original one, it works, but I'd like to modify the text fields on the cover page.

List of figures and tables

In addition to the table of contents (i.e. the toctree) is is possible to generate a "List of Figures" and "List of Tables" following the Table of Contents?

Image style are not applied

All the images have a standard paragraph style.

Do you reproduce the same problem ? Any idea what could be the cause ?

Thanks

First page title doesn't work

Conf.py

Output:

Body text has always zero left indentation

If you specify a style file that has a Body Text style with a non-zero left indentation (say 0,63 cm), the output docx file will have all paragraphs with zero left indentation (namely with style Body Text + Left 0 cm). A minimal rst will such as the following will do the trick:

================
This is a header
================

This is a bit of body text.

This is because the paragraph visitor makes new paragraphs with Contenxt objects that have explicitly zero indentation.

If I set the indent to None in the Paragraph constructor I do get the correct style, but that seems a bit like a hack and I'm not sure what else that will break.

Images are not shown with matplotlib.sphinxext.plot_directive

Is this project still alive?

When I try to build docx documentation with matplotlib, the images are not included in the document. Complete example:

# docs/conf.py
project = '…'
extensions = [
    'matplotlib.sphinxext.plot_directive',
    "docxbuilder",
]

Simple matplotlib plot
----------------------

.. plot::

   import matplotlib.pyplot as plt
   plt.plot([1, 2, 3], [4, 5, 6])
   plt.title("A plotting exammple")

produces a warning:

writing... /home/oles/sphinxword/docs/index.rst:: WARNING: Failed to get filepath

The plot files are both in the build directory, and in the plot_directive subdirectory of the build directory. The HTML build works fine here.

csv-table align option is ignored

The csv-table directive always produce a table with left-aligned cells, regardless of the :align: option being set to center or right. I would expect the resulting table to respect the alignement option attached with the csv-table directive, and default to left if none is provided.

Table caption position

Hello,

i have noticed that the table caption is displayed at the top of the table. Is it possible to have it located at the bottom of the table?

I tried to modify the position of the caption in the style file without any effect in the generated document.

Thank you

ReStructuredText Inline Markup not working

Hi,

An example table :

======= ==============================================================
01      **This Markup** does not translate to bold in my docx
======= ==============================================================

I did not find a workaround with table styles. In general I find docx table styles to be very confusing but that's an issue for microsoft. Some options like centered cells don't seem to do anything...

I did not try defining a character style for Bold and applying it my section like so:

:bold:`This Markup`

This could be a workaround if it works.

Thank you very much for this great project.

Problem with ToC numeration

Output:

Support for custom directive defined as extension

Hi all.

I have a custom directive defined as an extension (in a similar way as TODO example on sphinx page.

Problem is that this extension is used for html output via visit_my_node/depart_my_node methods, but I would have liked to implement a similar thing for docx builder.

I saw in the documentation that I should probably use a translator, but I can't really figure out how.

How should I proceed?

Change the languages of the paragraphs

Hello,

The language rendered in the docx paragraphs is english.

Is it possible to set another language in the rendered document ?

Use first page / section as cover page

Current implmentation uses structured data type (sdt) object with "Cover Pages" docPartGallery as cover page.
However, there are the following problem for this.

There are few ways to created such sdt object, and Most people don't know the ways.
LibreOffice or other applications may delete docPart information when cover page has no inline contents (#5).

Then, adding a new option to use first page or section as cover page.

Note, Warning etc directives are not formatted in DOCX

If I have the following code in RST ...

.. note::

test
test

... The result is in DOCX:

In HTML:

It is better to implement it in the extension. However there is a workaround but I need more information: which style is used in DOCX for note (I see a table with invisible borders, but I cannot figure out which style I should customize for it)?