Metadata-Version: 2.4
Name: sphinx2word
Version: 1.1.1
Summary: A Sphinx builder that writes Microsoft Word (.docx) documents directly, with native Word equations
Author-email: Nick Lloyd <nicklloyd5577@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ndl303/sphinx2word
Project-URL: Documentation, https://github.com/ndl303/sphinx2word/tree/main/docs
Project-URL: Changelog, https://github.com/ndl303/sphinx2word/blob/main/CHANGELOG.md
Classifier: Framework :: Sphinx :: Extension
Classifier: Topic :: Documentation :: Sphinx
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sphinx>=5
Provides-Extra: images
Requires-Dist: pillow; extra == "images"
Requires-Dist: cairosvg; extra == "images"
Provides-Extra: word
Requires-Dist: pywin32; sys_platform == "win32" and extra == "word"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pillow; extra == "test"
Dynamic: license-file

# sphinx2word

A [Sphinx](https://www.sphinx-doc.org) builder that writes your documentation as a Microsoft Word (`.docx`)
document. It writes the document using Office Open XML and works on Linux, Mac and Windows, including CI systems
such as GitHub Actions and GitLab CI. It does not need a physical instance of Word: the result is always a single, complete `.docx`
file, with its images and styles inside it.

Only Word can lay out the pages, so a document built without Word has its table of contents and lists of figures
and tables filled in, but without page numbers. When it is first opened, Word asks whether to update the fields in
the document; answer **Yes** to add the page numbers. Windows users with Word installed can avoid this extra step
by installing `pywin32` into their Python environment; the builder then lets Word fill in the page numbers during
the build. See [Building without Word](docs/numbering.md#building-without-word-linux-ci).

The result is a normal Word document that people can edit, comment on, restyle with their own template and merge into larger reports:

- **Equations:** LaTeX math becomes native, editable Word equations.
- **Headings:** headings use Word's heading styles, and Word numbers them.
- **Bibliographies** using Sphinx bibtex are supported.
- **Captions and cross-references:** captions and references are Word fields. Insert Caption, Cross-reference and
  Table of Figures all work, and the numbers follow the document when it is merged into another one.

Our group also works on various engineering contracts and we like to apply standard, front-style, content at the beginning of the
document. To help us support this we include options in the builder for,

- **Front matter:** a table of contents, a list of figures and a list of tables follow the title page.
- **Contract reports:** an optional cover page with contributor and distribution lists, and a change record taken
  from `conf.py` or from git tags.

We have configured the builder so it can use Word's internal scheme for labelling sections, figures, tables etc. This is
in contrast to the other option where we simply use the section/figure/table/equations numbers as generated by Sphinx.
This feature is important if you are merging multiple documents into one larger document and need to update all
figures, tables, equations, sections in one unified update. The variable `word_update_fields` in `conf.py` controls this feature. See
[Numbering, captions and cross-references](docs/numbering.md).

## Installation

```bash
pip install sphinx2word
```

The only mandatory dependency is Sphinx 5 or later (Python 3.8+). Some optional packages are used if they are
installed:

| Package           | Use                                                                                     |
|-------------------|-----------------------------------------------------------------------------------------|
| Pillow            | Read the size and resolution of JPEG, GIF, BMP and TIFF images (PNG and SVG are read without it) |
| cairosvg          | Make PNG fallbacks of SVG images for Word versions older than 2016                      |
| pywin32 (Windows) | With Word installed, let Word fill in the table of contents and page numbers after the build, so the file opens without a prompt. Without it the document is still written, and Word asks to update the fields the first time it is opened |

You can install the optional packages yourself or the installation will install the optional packages for you if you
supply the extra `images` (Pillow, cairosvg) and `word` (pywin32) options to the installation:

```bash
pip install "sphinx2word[images,word]"
```

## Quick start

Add the extension to `conf.py`:

```python
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.mathjax",
    # ...
    "sphinx2word",
]
```

and build with the `word` builder:

```bash
python -m sphinx -b word docs/source docs/_build/word
```

The output goes in the folder given on the command line, here `docs/_build/word`. The file is named
`<project>-<version>.docx` using the `project` and `version` variables in `conf.py`. Alternatively the filename can be set using variable
 `word_filename` in `conf.py` (see [Configuration](docs/configuration.md)). The whole toctree of the Sphinx document becomes one
Word document.

It can be helpful to modify your `conf.py` so the extension is only used if it is installed in your python environment,

```python
import importlib.util
if importlib.util.find_spec("sphinx2word") is not None:
    extensions.append("sphinx2word")
```

This is the technique we use in our CI/CD chain when we only wish to build HTML and do not want to install the ``sphinx2word`` package.


## What you get

| Sphinx / reStructuredText                         | Word                                                                  |
|---------------------------------------------------|-----------------------------------------------------------------------|
| Master document title                             | Title page, or the cover page of a contract report                    |
| —                                                 | Table of contents, list of figures, list of tables                    |
| Sections                                          | `Heading 1` … `Heading 9`; numbered by Word if the toctree is `:numbered:` |
| `:math:`, `.. math::`                             | Native Word equations; numbered equations have their number on the right |
| Figures and images (PNG, JPEG, GIF, BMP, TIFF, SVG) | Inline pictures with captions                                       |
| Tables (grid, simple, `list-table`, `csv-table`)  | Word tables with header rows, spanned cells, and lists and math in cells |
| Captions                                          | `Figure {SEQ Figure}: …`, as Word's Insert Caption writes them        |
| `:numref:`, `:eq:`, `:ref:`, `:doc:`              | Word cross-references (`REF` fields); other links are hyperlinks      |
| Footnotes                                         | Word footnotes                                                        |
| Citations (sphinxcontrib-bibtex or reST)          | Bibliography entries with aligned labels; citations link to them      |
| `code-block`, literal blocks                      | Shaded code blocks, coloured with Pygments, with line numbers and highlighted lines |
| `.. index::`, `:index:`, API entries              | Word index entries (`XE` fields) and an index at the end              |
| Python modules                                    | A Python module index before the index                                |
| `word_appendices`                                 | Appendices after the chapters, numbered "Appendix A:", A.1, A.1.1     |
| `language`                                        | Contents, lists, indexes and caption labels in the project's language |
| `graphviz`, `inheritance-diagram`                 | Diagrams drawn by Graphviz, inserted as pictures                      |
| `.. raw:: latex` `\newpage`, class `landscape`, `.. raw:: openxml` | Page breaks, landscape pages, and raw WordprocessingML |
| Lists (bullet, enumerated, definition, field, option) | Word lists; each enumerated list restarts at its own start number |
| note, warning, tip, todo, …                       | Shaded boxes with a coloured bar                                      |
| autodoc, napoleon, numpydoc, Breathe API entries  | Signature lines and indented descriptions                             |

Nodes that sphinx2word does not know are not dropped: their text is written as normal paragraphs, and the build
log lists their types. `.. only:: word` includes content in the Word output only.

## Documentation

| Page                                                        | Contents                                                        |
|-------------------------------------------------------------|-----------------------------------------------------------------|
| [Configuration](docs/configuration.md)                      | Every `word_*` setting in `conf.py`                             |
| [What is converted](docs/conversion.md)                     | How each Sphinx and reST construct appears in Word, and the limits |
| [Math](docs/math.md)                                        | The LaTeX supported in equations, macros, and what happens to errors |
| [Numbering, captions and cross-references](docs/numbering.md) | Word fields, caption numbering, merging into larger documents, the "update fields" prompt |
| [Contract reports](docs/contract-reports.md)                | Cover page, contributor and distribution lists, change record from git |
| [Word templates and styles](docs/templates.md)              | Using your own template, and the list of styles sphinx2word uses |
| [Example document](docs/example.md)                         | A complete Sphinx project that shows every feature, with its reST |
| [Development](docs/development.md)                          | Tests, code layout, checking the output in Word, CI and releases |
| [Changelog](https://github.com/ndl303/sphinx2word/blob/main/CHANGELOG.md) | What changed in each version                                    |

## Licence

MIT, © 2023-2026 Nick Lloyd. See [LICENSE](https://github.com/ndl303/sphinx2word/blob/main/LICENSE). You may use, copy, change and distribute sphinx2word, including
in commercial work, as long as you keep the copyright and licence notice.

## Origins

sphinx2word started as a fork of [docxsphinx](https://github.com/mherkazandjian/docxsphinx) by Mher Kazandjian and
Hugo Buddelmeijer, itself based on `sphinxcontrib-WordAppBuilder` by Takayuki Shimizukawa. Both are MIT-licensed.
Version 1.0 is a rewrite that writes the `.docx` file itself, but the project is grateful for where it began.
