sphinx-docx 1.0.0__tar.gz

sphinx_docx-1.0.0/CHANGELOG.rst

@@ -0,0 +1,11 @@
+Release 1.0.0 (2026-09-11)
+--------------------------
+
+First release under the name ``sphinx-docx``. Moved everything over from
+sphinx_docxbuilder-jm, which is now deprecated. The import name changed from
+``docxbuilder`` to ``sphinx_docx``; every ``docx_*`` configuration value and
+the ``docx`` builder name are unchanged, so only the ``extensions`` entry in
+**conf.py** has to be updated.
+
+The history before this point is the fork's, and of the ``docxbuilder``
+project it descends from.

sphinx_docx-1.0.0/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2009-2010 Mike MacCana
+Copyright (c) 2010 Takayuki SHIMIZUKAWA
+Copyright (c) 2011 Isao Hara
+Copyright (c) 2019 amedama41
+Copyright (c) 2022-2026 Nefti-sama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation 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 whom the 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 the Software.
+
+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 PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sphinx_docx-1.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE
+include CHANGELOG.rst
+include sphinx_docx/docx/LICENSE.python-docx
+
+# style.docx is generated at build time from these by create_style_file.py,
+# so both have to travel in the sdist for it to be buildable.
+include create_style_file.py
+recursive-include style_file/docx *
+
+exclude .gitattributes
+exclude .pylintrc
+exclude .readthedocs.yml
+prune .github
+prune .spec
+prune docs
+prune style_file/source

sphinx_docx-1.0.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: sphinx-docx
+Version: 1.0.0
+Summary: Sphinx extension that builds Word (.docx) documents
+Author: Nefti-sama
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Nefti-sama/sphinx-docx
+Project-URL: Repository, https://github.com/Nefti-sama/sphinx-docx
+Project-URL: Issues, https://github.com/Nefti-sama/sphinx-docx/issues
+Project-URL: Changelog, https://github.com/Nefti-sama/sphinx-docx/blob/main/CHANGELOG.rst
+Keywords: sphinx,sphinx-extension,docx,word,openxml,ooxml
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+License-File: sphinx_docx/docx/LICENSE.python-docx
+Requires-Dist: Sphinx>=9.0
+Requires-Dist: docutils>=0.22
+Requires-Dist: Pygments>=2.12
+Requires-Dist: lxml>=4.4
+Requires-Dist: Pillow>=6.1
+Requires-Dist: cairosvg>=2.5
+Requires-Dist: six>=1.16
+Provides-Extra: math
+Requires-Dist: latex2mathml; extra == "math"
+Requires-Dist: mathml2omml; extra == "math"
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=0.4.3; extra == "docs"
+Dynamic: license-file
+
+###########
+sphinx-docx
+###########
+
+sphinx-docx is a Sphinx extension to build docx formatted documents. The
+distribution is ``sphinx-docx``; the module you import and name in
+``extensions`` is ``sphinx_docx``.
+
+.. note::
+
+   This extension butchered the `original docxbuilder <https://github.com/amedama41/docxbuilder>`_ to add some functionality.
+
+Added:
+
+* SVG images: the vector is embedded for Word 2016+, with a png fallback
+* Multiple cover pages (`<https://github.com/amedama41/docxbuilder/pull/12>`_)
+* Directives the original ignored: ``autosummary``, ``inheritance-diagram``,
+  ``productionlist``, ``acks``, and PEP 695 type parameters in signatures
+* Per-admonition styles, so ``.. note::`` and ``.. warning::`` can look different
+* Sphinx 9 / docutils 0.22 compatibility (``findall``, ``FileOutput``)
+* Common color names for the highlight of ``:emphasize-lines:``
+
+
+************
+Requirements
+************
+
+:Python: 3.12 or later (developed and tested on 3.14)
+:Sphinx: 9.x or later
+
+*******
+Install
+*******
+
+::
+
+   pip install sphinx-docx
+
+For ``.. math::`` and the math role, which are rendered as OMML::
+
+   pip install "sphinx-docx[math]"
+
+Then add it to **conf.py**::
+
+   extensions = [
+       "sphinx_docx",
+   ]
+
+and build with::
+
+   sphinx-build -b docx source build/docx
+
+The development version::
+
+   pip install "sphinx-docx @ git+https://github.com/Nefti-sama/sphinx-docx.git"
+
+***********
+Development
+***********
+
+The default style file ``sphinx_docx/docx/style.docx`` is generated, not
+committed: ``create_style_file.py`` zips ``style_file/docx/`` into it, and
+``.gitignore`` excludes the result. ``setup.py`` hooks that into ``build_py``,
+which both a wheel build and a PEP 660 editable install run, so
+``pip install -e .`` produces it.
+
+Working straight from a clone without installing, regenerate it by hand after
+``git clean -xdf`` or ``make clean``::
+
+   python create_style_file.py
+
+Without it, any build which does not set ``docx_style`` in **conf.py** aborts
+with::
+
+   FileNotFoundError: [Errno 2] No such file or directory: '.../sphinx_docx/docx/style.docx'
+
+Edit the default style under ``style_file/docx/``, not ``style.docx`` itself;
+the latter is overwritten on the next regeneration. ``make update_style_file``
+does the full round trip, rebuilding ``style_file/docx/`` from the Sphinx
+project in ``style_file/`` first; note that it calls
+``./create_style_file.py``, which needs the executable bit and a ``python``
+on PATH.
+
+*****
+Usage
+*****
+
+Add 'sphinx_docx' to ``extensions`` configuration of **conf.py**:
+
+.. code:: python
+
+   extensions = ['sphinx_docx']
+
+and build your documents::
+
+   make docx
+
+You can control the generated document by adding configurations into ``conf.py``:
+
+.. code:: python
+
+   docx_documents = [
+       ('index', 'sphinx_docx.docx', {
+            'title': project,
+            'creator': author,
+            'subject': 'A manual of sphinx_docx',
+        }, True),
+   ]
+   docx_style = 'path/to/custom_style.docx'
+   docx_pagebreak_before_section = 1
+
+For more details, see `the (original) documentation <https://docxbuilder.readthedocs.io/en/latest/>`_.
+
+SVG images
+==========
+
+Use ``.. image::`` or ``.. figure::`` with an ``.svg`` file, as with any other
+image::
+
+   .. image:: diagram.svg
+      :width: 12cm
+
+Each SVG is embedded twice: the vector original, which Word 2016 and later
+draw sharp at any zoom, and a png rendered with cairosvg for older clients.
+
+Sizing follows the SVG's own ``width`` and ``height`` in any absolute unit
+(``px``, ``pt``, ``pc``, ``in``, ``cm``, ``mm``), falling back to the
+``viewBox`` when they are missing or relative. ``:width:`` and ``:height:``
+override that as usual.
+
+``cairosvg`` is installed as a dependency. Without it the build still
+succeeds; every SVG is skipped with a warning instead of aborting.
+
+Images an SVG pulls in with an ``href`` (another svg, a bitmap) are inlined as
+data URIs, so they survive the move into the docx. References made through CSS
+``url()`` are not, and draw empty (#TODO).
+
+CSS custom properties are substituted before either renderer sees the file,
+because neither cairosvg nor Word implements them. ``var(--bg, #ffffff)``
+becomes ``#ffffff``; a ``var()`` with no fallback takes the value declared for
+it elsewhere in the file, and one with neither becomes ``none``. Drawio 
+emit these constantly -- a recent draw.io SVG is full of them -- and
+without the substitution cairosvg fails the whole image with ``invalid literal
+for int() with base 16``.
+
+Directives
+==========
+
+Beyond what the original builder handles:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Directive
+     - Rendered as
+   * - ``.. autosummary::``
+     - the summary table, and with ``:toctree:`` the generated stub pages
+   * - ``.. inheritance-diagram::``
+     - a graphviz image, through the same path as ``.. graphviz::``
+   * - ``.. productionlist::``
+     - a borderless two-column table, styled ``Production List``
+   * - ``.. acks::``
+     - the contained bullet list
+   * - ``.. py:class:: Widget[T]``
+     - PEP 695 type parameters, in square brackets
+
+Admonitions take one table style per type, not a shared one: ``.. note::``
+uses ``Admonition Note``, ``.. warning::`` uses ``Admonition Warning``, and a
+``.. admonition:: My Title`` uses ``Admonition My Title``. Define the style in
+your style file to change how that one type looks. Types you do not define get
+a style created from ``Based Admonition``, so nothing breaks if it is missing.
+
+Code highlighting
+=================
+
+``:emphasize-lines:`` highlights a line with the ``highlight_color`` of the
+Pygments style, which is normally a hex string. A common color name is
+accepted too:
+
+.. code:: python
+
+   # in conf.py, or a style module on sys.path
+   from pygments.styles.default import DefaultStyle
+
+   class MyStyle(DefaultStyle):
+       highlight_color = 'lightgreen'
+
+   pygments_style = 'mystyle.MyStyle'
+
+Word does not take a color here: its ``w:highlight`` accepts only the fifteen
+names of the OOXML ``ST_HighlightColor`` list, and a file using any other name
+is invalid. So the requested color is snapped to the nearest name Word does
+have, matching hue before brightness. ``lightgreen`` and ``lime`` highlight
+green, ``orange`` and ``gold`` yellow, ``navy`` dark blue.
+
+
+Style file
+==========
+
+Generated docx file's design is customized by a style file
+(The default style is ``sphinx_docx/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
+* Production List
+* Admonition, Admonition Note, Admonition Warning, ...
+
+****
+TODO
+****
+
+- Support URL path for images.
+- Follow CSS ``url()`` references inside SVG images.
+
+*******
+Licence
+*******
+
+MIT Licence
+

sphinx_docx-1.0.0/README.rst

@@ -0,0 +1,247 @@
+###########
+sphinx-docx
+###########
+
+sphinx-docx is a Sphinx extension to build docx formatted documents. The
+distribution is ``sphinx-docx``; the module you import and name in
+``extensions`` is ``sphinx_docx``.
+
+.. note::
+
+   This extension butchered the `original docxbuilder <https://github.com/amedama41/docxbuilder>`_ to add some functionality.
+
+Added:
+
+* SVG images: the vector is embedded for Word 2016+, with a png fallback
+* Multiple cover pages (`<https://github.com/amedama41/docxbuilder/pull/12>`_)
+* Directives the original ignored: ``autosummary``, ``inheritance-diagram``,
+  ``productionlist``, ``acks``, and PEP 695 type parameters in signatures
+* Per-admonition styles, so ``.. note::`` and ``.. warning::`` can look different
+* Sphinx 9 / docutils 0.22 compatibility (``findall``, ``FileOutput``)
+* Common color names for the highlight of ``:emphasize-lines:``
+
+
+************
+Requirements
+************
+
+:Python: 3.12 or later (developed and tested on 3.14)
+:Sphinx: 9.x or later
+
+*******
+Install
+*******
+
+::
+
+   pip install sphinx-docx
+
+For ``.. math::`` and the math role, which are rendered as OMML::
+
+   pip install "sphinx-docx[math]"
+
+Then add it to **conf.py**::
+
+   extensions = [
+       "sphinx_docx",
+   ]
+
+and build with::
+
+   sphinx-build -b docx source build/docx
+
+The development version::
+
+   pip install "sphinx-docx @ git+https://github.com/Nefti-sama/sphinx-docx.git"
+
+***********
+Development
+***********
+
+The default style file ``sphinx_docx/docx/style.docx`` is generated, not
+committed: ``create_style_file.py`` zips ``style_file/docx/`` into it, and
+``.gitignore`` excludes the result. ``setup.py`` hooks that into ``build_py``,
+which both a wheel build and a PEP 660 editable install run, so
+``pip install -e .`` produces it.
+
+Working straight from a clone without installing, regenerate it by hand after
+``git clean -xdf`` or ``make clean``::
+
+   python create_style_file.py
+
+Without it, any build which does not set ``docx_style`` in **conf.py** aborts
+with::
+
+   FileNotFoundError: [Errno 2] No such file or directory: '.../sphinx_docx/docx/style.docx'
+
+Edit the default style under ``style_file/docx/``, not ``style.docx`` itself;
+the latter is overwritten on the next regeneration. ``make update_style_file``
+does the full round trip, rebuilding ``style_file/docx/`` from the Sphinx
+project in ``style_file/`` first; note that it calls
+``./create_style_file.py``, which needs the executable bit and a ``python``
+on PATH.
+
+*****
+Usage
+*****
+
+Add 'sphinx_docx' to ``extensions`` configuration of **conf.py**:
+
+.. code:: python
+
+   extensions = ['sphinx_docx']
+
+and build your documents::
+
+   make docx
+
+You can control the generated document by adding configurations into ``conf.py``:
+
+.. code:: python
+
+   docx_documents = [
+       ('index', 'sphinx_docx.docx', {
+            'title': project,
+            'creator': author,
+            'subject': 'A manual of sphinx_docx',
+        }, True),
+   ]
+   docx_style = 'path/to/custom_style.docx'
+   docx_pagebreak_before_section = 1
+
+For more details, see `the (original) documentation <https://docxbuilder.readthedocs.io/en/latest/>`_.
+
+SVG images
+==========
+
+Use ``.. image::`` or ``.. figure::`` with an ``.svg`` file, as with any other
+image::
+
+   .. image:: diagram.svg
+      :width: 12cm
+
+Each SVG is embedded twice: the vector original, which Word 2016 and later
+draw sharp at any zoom, and a png rendered with cairosvg for older clients.
+
+Sizing follows the SVG's own ``width`` and ``height`` in any absolute unit
+(``px``, ``pt``, ``pc``, ``in``, ``cm``, ``mm``), falling back to the
+``viewBox`` when they are missing or relative. ``:width:`` and ``:height:``
+override that as usual.
+
+``cairosvg`` is installed as a dependency. Without it the build still
+succeeds; every SVG is skipped with a warning instead of aborting.
+
+Images an SVG pulls in with an ``href`` (another svg, a bitmap) are inlined as
+data URIs, so they survive the move into the docx. References made through CSS
+``url()`` are not, and draw empty (#TODO).
+
+CSS custom properties are substituted before either renderer sees the file,
+because neither cairosvg nor Word implements them. ``var(--bg, #ffffff)``
+becomes ``#ffffff``; a ``var()`` with no fallback takes the value declared for
+it elsewhere in the file, and one with neither becomes ``none``. Drawio 
+emit these constantly -- a recent draw.io SVG is full of them -- and
+without the substitution cairosvg fails the whole image with ``invalid literal
+for int() with base 16``.
+
+Directives
+==========
+
+Beyond what the original builder handles:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Directive
+     - Rendered as
+   * - ``.. autosummary::``
+     - the summary table, and with ``:toctree:`` the generated stub pages
+   * - ``.. inheritance-diagram::``
+     - a graphviz image, through the same path as ``.. graphviz::``
+   * - ``.. productionlist::``
+     - a borderless two-column table, styled ``Production List``
+   * - ``.. acks::``
+     - the contained bullet list
+   * - ``.. py:class:: Widget[T]``
+     - PEP 695 type parameters, in square brackets
+
+Admonitions take one table style per type, not a shared one: ``.. note::``
+uses ``Admonition Note``, ``.. warning::`` uses ``Admonition Warning``, and a
+``.. admonition:: My Title`` uses ``Admonition My Title``. Define the style in
+your style file to change how that one type looks. Types you do not define get
+a style created from ``Based Admonition``, so nothing breaks if it is missing.
+
+Code highlighting
+=================
+
+``:emphasize-lines:`` highlights a line with the ``highlight_color`` of the
+Pygments style, which is normally a hex string. A common color name is
+accepted too:
+
+.. code:: python
+
+   # in conf.py, or a style module on sys.path
+   from pygments.styles.default import DefaultStyle
+
+   class MyStyle(DefaultStyle):
+       highlight_color = 'lightgreen'
+
+   pygments_style = 'mystyle.MyStyle'
+
+Word does not take a color here: its ``w:highlight`` accepts only the fifteen
+names of the OOXML ``ST_HighlightColor`` list, and a file using any other name
+is invalid. So the requested color is snapped to the nearest name Word does
+have, matching hue before brightness. ``lightgreen`` and ``lime`` highlight
+green, ``orange`` and ``gold`` yellow, ``navy`` dark blue.
+
+
+Style file
+==========
+
+Generated docx file's design is customized by a style file
+(The default style is ``sphinx_docx/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
+* Production List
+* Admonition, Admonition Note, Admonition Warning, ...
+
+****
+TODO
+****
+
+- Support URL path for images.
+- Follow CSS ``url()`` references inside SVG images.
+
+*******
+Licence
+*******
+
+MIT Licence
+

sphinx_docx-1.0.0/create_style_file.py

@@ -0,0 +1,26 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+from __future__ import print_function
+import os
+import zipfile
+
+def create_style_file():
+    base_dir = os.path.dirname(os.path.abspath(__file__))
+    style_file_path = os.path.normpath(
+            os.path.join(base_dir, 'sphinx_docx/docx/style.docx'))
+    print('creating %s' % style_file_path)
+    style_file = zipfile.ZipFile(
+            style_file_path, mode='w', compression=zipfile.ZIP_DEFLATED)
+    def addfile(dirpath, rootpath):
+        for filename in os.listdir(dirpath):
+            path = os.path.join(dirpath, filename)
+            if os.path.isdir(path):
+                addfile(path, rootpath + filename + '/')
+            else:
+                style_file.write(path, rootpath + filename)
+    addfile(os.path.join(base_dir, 'style_file/docx'), '')
+    style_file.close()
+
+if __name__ == '__main__':
+    create_style_file()
+

sphinx_docx-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sphinx-docx"
+version = "1.0.0"
+description = "Sphinx extension that builds Word (.docx) documents"
+readme = { file = "README.rst", content-type = "text/x-rst" }
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE", "sphinx_docx/docx/LICENSE.python-docx"]
+authors = [{ name = "Nefti-sama" }]
+keywords = ["sphinx", "sphinx-extension", "docx", "word", "openxml", "ooxml"]
+
+# cairosvg and Pillow are imported lazily, only when a document contains an
+# SVG or a raster image, but SVG support is a headline feature of this fork so
+# they are hard requirements rather than an extra.
+dependencies = [
+    "Sphinx>=9.0",
+    "docutils>=0.22",
+    "Pygments>=2.12",
+    "lxml>=4.4",
+    "Pillow>=6.1",
+    "cairosvg>=2.5",
+    "six>=1.16",
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Framework :: Sphinx",
+    "Framework :: Sphinx :: Extension",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation :: Sphinx",
+    "Topic :: Text Processing :: Markup",
+    "Topic :: Software Development :: Documentation",
+]
+
+[project.optional-dependencies]
+# `.. math::` and the math role are rendered as OMML through these.
+math = ["latex2mathml", "mathml2omml"]
+docs = ["sphinx-rtd-theme>=0.4.3"]
+
+[project.urls]
+Homepage = "https://github.com/Nefti-sama/sphinx-docx"
+Repository = "https://github.com/Nefti-sama/sphinx-docx"
+Issues = "https://github.com/Nefti-sama/sphinx-docx/issues"
+Changelog = "https://github.com/Nefti-sama/sphinx-docx/blob/main/CHANGELOG.rst"
+
+[tool.setuptools]
+packages = ["sphinx_docx", "sphinx_docx.docx"]
+
+[tool.setuptools.package-data]
+# Generated from style_file/docx/ by create_style_file.py at build time.
+"sphinx_docx.docx" = ["style.docx"]

sphinx_docx-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+