README.md 2.93 KB
Newer Older
1 2 3 4 5 6 7 8
# Documentation utilities

## Overview

This repository is a collection of styles and patched scripts for the Python docutils package to generate pleasant
documents from reStructuredText files.


9 10 11 12 13 14 15
## Python package

This repository contains a Python package `docutils_extended` that can be installed with `pip`:

```bash
pip install git+https://iffgit.fz-juelich.de/doc-utils/doc-utils
```
16

17 18
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:
19

20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
-   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.
51 52 53


## Files
54

55 56 57 58 59 60
-   `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