# ichec_handbook
`ichec_handbook` is a 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](https://ichec-handbook.readthedocs.io/en/latest/src/frontmatter.html) and others.
# Features #
The project is a [Jupyter Book](https://jupyterbook.org/en/stable/intro.html) wrapper that can build 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 `ichec_handbook` you can add some additional build configurations to the existing `_config.yml` under an `ichec_handbook` key, for example:
``` yaml
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
ichec_handbook:
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:
``` shell
ichec_handbook book --source_dir $SOURCE_DIR
```
where `SOURCE_DIR` is the location of the book sources.
# Installation #
If you are only using this project to build books, the container approach is strongly recommended due to complex runtime dependencies. You can follow the container guide in [infra](./infra/README.md).
If you want a full native version, you first need to install the project dependencies. First, `imagemagick` and `cairo` for image format conversion:
``` shell
brew install imagemagick cairo
```
Next, a full Latex environment, on Mac you can use [MacTeX](https://www.tug.org/mactex/mactex-download.html)
Finally you need a working version of the [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli).
After installing dependencies you can install the project with:
``` shell
pip install ichec_handbook
```
# Contact #
For further information you can contact `james.grogan@ichec.ie`.
# Copyright #
Copyright 2025 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "ichec-handbook",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Publishing, Technical Reports",
"author": null,
"author_email": "\"Platform Engineering Team, Irish Centre for High End Computing\" <platform_engineering@ichec.ie>",
"download_url": "https://files.pythonhosted.org/packages/41/25/14467e9e37c4ed38d7240c51b32c6ea0ab6b78d9f2c14592683891e4c8d8/ichec_handbook-0.2.0.tar.gz",
"platform": null,
"description": "# ichec_handbook\n\n`ichec_handbook` is a 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](https://ichec-handbook.readthedocs.io/en/latest/src/frontmatter.html) and others.\n\n# Features #\n\nThe project is a [Jupyter Book](https://jupyterbook.org/en/stable/intro.html) wrapper that can build multiple configurations of a book based on tags in document frontmatter, allowing the concept of 'public', 'private' or 'draft' versions.\n\nIn particular, it allows:\n\n* Rendering of different book versions (e.g. `public`, `private`, `draft`) based on document frontmatter tags\n* Automatic conversion of image formats (including TIKZ and mermaid) to best suit the output format (web, PDF etc).\n* Named build configurations specified in YAML, allowing rendering of multiple versions in the same build job.\n* Book version numbering\n\n# Usage #\n\nAssuming a repository has been set up for a standard Jupyter Book build, to use `ichec_handbook` you can add some additional build configurations to the existing `_config.yml` under an `ichec_handbook` key, for example:\n\n``` yaml\ntitle: Mock Book\nauthor: Mock Book Author\nexclude_patterns: [/src/media, infra/, infra/README.md, _build, .venv]\nonly_build_toc_files: true\nsphinx:\n config:\n myst_heading_anchors: 3\nlatex:\n latex_documents:\n targetname: book.tex\nichec_handbook:\n project_name: mock_book\n version: 0.0.0\n builds:\n - name: \"internal\"\n outputs:\n - \"pdf\"\n - \"html\"\n - \"src\"\n - name: \"public\"\n outputs:\n - \"pdf\"\n - \"html\"\n - \"src\"\n include_tags:\n - \"public\"\n```\n\nhere 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').\n\nTo do the builds run: \n\n``` shell\nichec_handbook book --source_dir $SOURCE_DIR \n```\n\nwhere `SOURCE_DIR` is the location of the book sources.\n\n\n# Installation #\n\nIf you are only using this project to build books, the container approach is strongly recommended due to complex runtime dependencies. You can follow the container guide in [infra](./infra/README.md).\n\nIf you want a full native version, you first need to install the project dependencies. First, `imagemagick` and `cairo` for image format conversion:\n\n``` shell\nbrew install imagemagick cairo\n```\n\nNext, a full Latex environment, on Mac you can use [MacTeX](https://www.tug.org/mactex/mactex-download.html)\n\nFinally you need a working version of the [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli).\n\n\nAfter installing dependencies you can install the project with:\n\n``` shell\npip install ichec_handbook\n```\n\n# Contact #\n\nFor further information you can contact `james.grogan@ichec.ie`. \n\n# Copyright #\n\nCopyright 2025 Irish Centre for High End Computing\n\nThe software in this repository can be used under the conditions of the GPLv3+ license, which is available for reading in the accompanying `LICENSE` file.\n\nIf you are an ICHEC collaborator or National Service user and hope to use this library under different terms please get in touch.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tool to build handbooks.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://git.ichec.ie/platform-engineering/ichec-handbook",
"Repository": "https://git.ichec.ie/platform-engineering/ichec-handbook"
},
"split_keywords": [
"publishing",
" technical reports"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7312f9e808d805de3c0e4c686e5b3b7e7f3e81d838b08ce8ab1476cb56fd5e68",
"md5": "e6579053fe4e641a76a53247908c68fd",
"sha256": "78a670468b5cdc47a1531a51d41f6df7fad0329e5a0b5bd16510dbcd9c59da31"
},
"downloads": -1,
"filename": "ichec_handbook-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6579053fe4e641a76a53247908c68fd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 32955,
"upload_time": "2025-08-08T10:43:57",
"upload_time_iso_8601": "2025-08-08T10:43:57.081852Z",
"url": "https://files.pythonhosted.org/packages/73/12/f9e808d805de3c0e4c686e5b3b7e7f3e81d838b08ce8ab1476cb56fd5e68/ichec_handbook-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "412514467e9e37c4ed38d7240c51b32c6ea0ab6b78d9f2c14592683891e4c8d8",
"md5": "27fe2903ef8147584f6fc48ac87c3ff3",
"sha256": "e2b428939022519a1d86065a3f4c8841b7d0902dc9b04302f19e82bbf1120554"
},
"downloads": -1,
"filename": "ichec_handbook-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "27fe2903ef8147584f6fc48ac87c3ff3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 29023,
"upload_time": "2025-08-08T10:43:58",
"upload_time_iso_8601": "2025-08-08T10:43:58.588618Z",
"url": "https://files.pythonhosted.org/packages/41/25/14467e9e37c4ed38d7240c51b32c6ea0ab6b78d9f2c14592683891e4c8d8/ichec_handbook-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 10:43:58",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ichec-handbook"
}
JSON