icreports 0.0.13

Utilities for generating technical reports.

icreports

icreports is a configuration management tool for generating e-books and technical documents. It is used at the Irish Centre for High End Computing (ICHEC) to build the ICHEC handbook.

Features

The project is based on the Jupyter Book toolchain and formats, providing a wrapper that allows building multiple configurations of a book based on tags in document frontmatter, allowing the concept of 'public', 'private' or 'draft' versions.

In particular, it allows:

• Rendering of different book versions (e.g. public, private, draft) based on document frontmatter tags
• Automatic conversion of image formats (including TIKZ and mermaid) to best suit the output format (web, PDF etc).
• Named build configurations specified in YAML, allowing rendering of multiple versions in the same build job.
• Book version numbering

Usage

Assuming a repository has been set up for a standard Jupyter Book build, to use icreports you can add some build configurations to the existing _config.yml under an icreports key, for example:

title: Mock Book
author: Mock Book Author
exclude_patterns: [/src/media, infra/, infra/README.md, _build, .venv]
only_build_toc_files: true
sphinx:
  config:
    myst_heading_anchors: 3
latex:
  latex_documents:
     targetname: book.tex
icreports:
  project_name: mock_book
  version: 0.0.0
  builds:
    - name: "internal"
      outputs:
        - "pdf"
        - "html"
        - "src"
    - name: "public"
      outputs:
        - "pdf"
        - "html"
        - "src"
      include_tags:
        - "public"

here the book is given a version and two builds 'internal' and 'public' are specified. The public build will only include documents that have the tag 'public' in their frontmatter, through the use of the 'include_tags' attribute. All supported output formats 'pdf', 'html' and 'src' (just copy all sources) are requested in this case. This will lead to four invocations of Jupyter Book (and two custom copy operations for 'src').

To do the builds run:

icreports book --source_dir $SOURCE_DIR 

where SOURCE_DIR is the location of the book sources.

Installation

The project is available on PyPi, you can install it with:

pip install icreports

Some features rely on converting images between various formats. For full image format support imagemagick, cairo and a full LaTeX environment are required. On Mac you can install the former with brew, with MacTeX used to install the LaTeX environment.

Using a container

Follow the guide in infra to use a container to build with.

Contact

For further information you can contact [e-mail]. Due to our current Gitlab hosting setup we can't easily accept contributions or defect reports via that platform. We may in future set up a mirror if of interest - please get in touch by email with any defect reports or other feedback in the meantime.

Copyright

Copyright 2024 Irish Centre for High End Computing

The software in this repository can be used under the conditions of the GPLv3+ license, which is available for reading in the accompanying LICENSE file.

If you are an ICHEC collaborator or National Service user and hope to use this library under different terms please get in touch.