Merge branch 'develop'

README.md

@@ -17,19 +17,44 @@ pip install git+https://iffgit.fz-juelich.de/doc-utils/doc-utils
 After installing you can use the extended rst writers `rst2latex-extended` and `rst2html-extended` that are compatible
 with the standard versions but offer additional features:
 
-- Code blocks are formatted with the `minted` package (LaTeX only)
-- Images can be embedded into the generated document (`embedded-image` directive, HTML only; for LaTeX this is already
-  the default behavior)
-- Support for TikZ images by `tikz` and `tikz-figure` directives. TikZ code can be loaded from an external file or
-  written as embedded source. `rst2html-extended` needs either `pdf2svg` or `mupdf-tools` to support TikZ pictures.
-  `pdf2svg` is recommended because it produces SVG images without any quality loss.
+-   Code blocks are formatted with the `minted` package (LaTeX only).
+-   Images can be embedded into the generated document (`embedded-image` and `embedded-figure` directives). Adds an
+    additional convert step if the graphics format is not suitable for the output (SVG images are converted to PDF and
+    GIF to PNG for LaTeX output). If the image path is a web link, the image is downloaded before.
+-   Support for TikZ images by `tikz` and `tikz-figure` directives. TikZ code can be loaded from an external file or
+    written as embedded source. `rst2html-extended` needs either `pdf2svg` or `mupdf-tools` to support TikZ pictures.
+    `pdf2svg` is recommended because it produces SVG images without any quality loss.
+
+
+### Directive options
+
+-   `tikz` and `tikz-figure`:
+
+    -   Both directives inherit `alt`, `height`, `width`, `scale`, `align`, `name`, `target` and `class` from the `image`
+        directive.
+    -   Both directives have the additional options:
+
+        -   `document_options`: Extra options for the LaTeX
+            [`standalone` document class](https://ctan.org/pkg/standalone?lang=en)
+        -   `lang`: Babel language
+        -   `do_not_use_default_packages`: Do not load these default packages: `inputenc`, `fontenc`, `lmodern`,
+            `babel`, `xcolor`, `graphicx`
+        -   `extra_packages`: Extra packages to load, can be used like this: `[options]{package};[options]{package}`
+        -   `tikz_libs`: Additional TikZ libraries to load, separated by comma, e.g.: `arrows,calc`
+        -   `tikzpicture_options`: Additional tikzpicture options, for example: `overlay`
+
+    -   The `tikz-figure` directive has the additional options `figwidth` and `caption` like other `figure` objects.
+
+-   `embedded-image` and `embedded-figure`:
+
+    -   All options are identical to the usual `image` and `figure` directives.
 
 
 ## Files
 
-- `styles/rst2html_githublike_fzj.css`: Stylesheet for `rst2html` with fzj blue for strong emphasized text; Using
-  `--syntax-highlight=short` option with `rst2html` is recommended but long class names are also included in the this
-  CSS file
-- `styles/rst2latex_fzj.sty`: Style with fzj colors and a custom title page
-- `styles/rst2luatex_fzj.sty`: Style with fzj colors and a custom title page for use with LuaTex / LuaLaTeX
-- `utils/Makefile`: Example Makefile for generating PDFs and HTML pages from Markdown and reStructuredText documents
+-   `styles/rst2html_githublike_fzj.css`: Stylesheet for `rst2html` with fzj blue for strong emphasized text; Using
+    `--syntax-highlight=short` option with `rst2html` is recommended but long class names are also included in the this
+    CSS file.
+-   `styles/rst2latex_fzj.sty`: Style with fzj colors and a custom title page
+-   `styles/rst2luatex_fzj.sty`: Style with fzj colors and a custom title page for use with LuaTex / LuaLaTeX
+-   `utils/Makefile`: Example Makefile for generating PDFs and HTML pages from Markdown and reStructuredText documents

docutils_extended/_version.py

-__version_info__ = (0, 2, 2)
+__version_info__ = (0, 2, 3)
 __version__ = '.'.join(map(str, __version_info__))

docutils_extended/directives/__init__.py

 from .code_directive import CodeBlock
-from .embedded_image_directive import EmbeddedImage
+from .embedded_image_directive import EmbeddedImage, EmbeddedFigure
 from .jupyter_outbox_directive import JupyterOutbox
 from .tikz_directive import Tikz, TikzFigure
 from .output_mode import get_output_mode, set_output_mode
 
 
-__all__ = ("CodeBlock", "EmbeddedImage", "JupyterOutbox", "Tikz", "TikzFigure", "get_output_mode", "set_output_mode")
+__all__ = ("CodeBlock", "EmbeddedImage", "EmbeddedFigure", "JupyterOutbox", "Tikz", "TikzFigure", "get_output_mode",
+           "set_output_mode")

docutils_extended/directives/embedded_image_directive.py

@@ -181,3 +181,32 @@ class EmbeddedImage(Directive):
             return messages + [reference_node]
         else:
             return messages + [image_node]
+
+
+class EmbeddedFigure(EmbeddedImage):
+    option_spec = EmbeddedImage.option_spec.copy()
+    option_spec["figwidth"] = lambda argument: directives.length_or_percentage_or_unitless(argument, "px")
+    option_spec["figclass"] = directives.class_option
+    option_spec["align"] = lambda argument: directives.choice(argument, EmbeddedFigure.align_values)
+    option_spec["caption"] = directives.unchanged
+    has_content = True
+
+    def run(self):
+        figwidth = self.options.pop("figwidth", None)
+        figclasses = self.options.pop("figclass", None)
+        align = self.options.pop("align", None)
+        caption = self.options.pop("caption", None)
+        (image_node,) = EmbeddedImage.run(self)
+        if isinstance(image_node, nodes.system_message):
+            return [image_node]
+        figure_node = nodes.figure("", image_node)
+        if figwidth is not None:
+            figure_node["width"] = figwidth
+        if figclasses:
+            figure_node["classes"] += figclasses
+        if align:
+            figure_node["align"] = align
+        if caption:
+            caption = nodes.caption("", text=caption)
+            figure_node += caption
+        return [figure_node]

docutils_extended/writers/rst2html_extended.py

@@ -19,7 +19,7 @@ except:
 from docutils.core import publish_cmdline, default_description
 from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.body import ParsedLiteral
-from ..directives import EmbeddedImage, Tikz, TikzFigure, set_output_mode
+from ..directives import EmbeddedImage, EmbeddedFigure, Tikz, TikzFigure, set_output_mode
 
 
 description = "Generates (X)HTML documents from standalone reStructuredText " "sources.  " + default_description
@@ -28,6 +28,7 @@ description = "Generates (X)HTML documents from standalone reStructuredText " "s
 def main():
     set_output_mode("html")
     directives.register_directive("embedded-image", EmbeddedImage)
+    directives.register_directive("embedded-figure", EmbeddedFigure)
     directives.register_directive("jupyter-outbox", ParsedLiteral)
     directives.register_directive("tikz", Tikz)
     directives.register_directive("tikz-figure", TikzFigure)

docutils_extended/writers/rst2latex_extended.py

@@ -19,7 +19,7 @@ except:
 
 from docutils.core import publish_cmdline
 from docutils.parsers.rst import directives
-from ..directives import CodeBlock, EmbeddedImage, JupyterOutbox, Tikz, TikzFigure, set_output_mode
+from ..directives import CodeBlock, EmbeddedImage, EmbeddedFigure, JupyterOutbox, Tikz, TikzFigure, set_output_mode
 
 
 description = (
@@ -37,6 +37,7 @@ def main():
     for directive_name in ("code", "code-block"):
         directives.register_directive(directive_name, CodeBlock)
     directives.register_directive("embedded-image", EmbeddedImage)
+    directives.register_directive("embedded-figure", EmbeddedFigure)
     directives.register_directive("jupyter-outbox", JupyterOutbox)
     directives.register_directive("tikz", Tikz)
     directives.register_directive("tikz-figure", TikzFigure)