# 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.


## 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
```

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 `listings` 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.


## 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
- `utils/Makefile`: Example Makefile for generating PDFs and HTML pages from Markdown and reStructuredText documents