README.md 1.34 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
- 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
28

29 30 31 32 33
- `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