Commit a5c52c2a authored by Ingo Meyer's avatar Ingo Meyer

Merge branch 'develop'

parents 613de438 b173e995
......@@ -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
__version_info__ = (0, 2, 2)
__version_info__ = (0, 2, 3)
__version__ = '.'.join(map(str, __version_info__))
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")
......@@ -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]
......@@ -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)
......
......@@ -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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment