| Name | icreports JSON |
| Version |
0.0.12
JSON |
| download |
| home_page | None |
| Summary | Utilities for generating technical reports. |
| upload_time | 2024-12-10 16:34:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
publishing
technical reports
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# icreports
`icreports` is a configuration management tool (à la CMake) 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).
# Features #
The project is based on the [Jupyter Book](https://jupyterbook.org/en/stable/intro.html) 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) 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
## Why is this useful? ##
At ICHEC (at least) we want a handbook that is as easy as possible to contribute to. But the people who maintain the handbook don't have easy access to the centre's hosting infrastructure - so it isn't easy to 'self-host' web services that we need. Ideally we live in a DevOps world where this is possible - but we aren't there yet. This library sidesteps this by relying on public infrastructure like ReadTheDocs to do the document build and hosting. However, we want 'internal' info in the handbook too. The convoluted steps needed to maintain public and internal handbook versions while also building on piecemeal public infrastructures motivated this tool. Maybe you are in a similar situation and it can be helpful for you too.
# 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:
``` 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
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:
``` shell
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:
``` shell
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 ##
If you prefer not to set up the dependencies or are having issues with them you can use a container to do the build. Assuming you have `podman` or `docker` installed you can do:
``` shell
cd infra
podman build --platform linux/arm64 -t icreports .
podman run -it -v $SOURCE_DIR:/src -v $BUILD_DIR/:/build -p 8000:8000 --platform linux/arm64 icreports
```
The `SOURCE_DIR` is the path to the book sources on the host. The `BUILD_DIR` is somewhere you want build output to go on the host. `--platform` can be omitted on `x86_64` systems.
Build output will also be served at [localhost:8000](http://localhost:8000), which you can open in a web browser.
# Contact #
For further information you can contact `james.grogan@ichec.ie`. 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "icreports",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Publishing, Technical Reports",
"author": null,
"author_email": "\"James Grogan, Irish Centre for High End Computing\" <james.grogan@ichec.ie>",
"download_url": "https://files.pythonhosted.org/packages/60/51/d46c8d123cece54be841c8be30d2ecdbfe0ce1ef9e132569a281166c996a/icreports-0.0.12.tar.gz",
"platform": null,
"description": "# icreports\n\n`icreports` is a configuration management tool (\u00e0 la CMake) 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).\n\n# Features #\n\nThe project is based on the [Jupyter Book](https://jupyterbook.org/en/stable/intro.html) 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.\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) 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## Why is this useful? ##\n\nAt ICHEC (at least) we want a handbook that is as easy as possible to contribute to. But the people who maintain the handbook don't have easy access to the centre's hosting infrastructure - so it isn't easy to 'self-host' web services that we need. Ideally we live in a DevOps world where this is possible - but we aren't there yet. This library sidesteps this by relying on public infrastructure like ReadTheDocs to do the document build and hosting. However, we want 'internal' info in the handbook too. The convoluted steps needed to maintain public and internal handbook versions while also building on piecemeal public infrastructures motivated this tool. Maybe you are in a similar situation and it can be helpful for you too.\n\n# Usage #\n\nAssuming 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:\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\nicreports:\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\nicreports book --source_dir $SOURCE_DIR \n```\n\nwhere `SOURCE_DIR` is the location of the book sources.\n\n\n# Installation #\n\nThe project is available on PyPi, you can install it with:\n\n``` shell\npip install icreports\n```\n\nSome 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.\n\n## Using a container ##\n\nIf you prefer not to set up the dependencies or are having issues with them you can use a container to do the build. Assuming you have `podman` or `docker` installed you can do:\n\n``` shell\ncd infra\npodman build --platform linux/arm64 -t icreports .\npodman run -it -v $SOURCE_DIR:/src -v $BUILD_DIR/:/build -p 8000:8000 --platform linux/arm64 icreports\n```\n\nThe `SOURCE_DIR` is the path to the book sources on the host. The `BUILD_DIR` is somewhere you want build output to go on the host. `--platform` can be omitted on `x86_64` systems. \n\nBuild output will also be served at [localhost:8000](http://localhost:8000), which you can open in a web browser.\n\n# Contact #\n\nFor further information you can contact `james.grogan@ichec.ie`. 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.\n\n# Copyright #\n\nCopyright 2024 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": "Utilities for generating technical reports.",
"version": "0.0.12",
"project_urls": {
"Homepage": "https://git.ichec.ie/performance/toolshed/icreports",
"Repository": "https://git.ichec.ie/performance/toolshed/icreports"
},
"split_keywords": [
"publishing",
" technical reports"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c7ba3f5a7d16213f01c38c32293427d7f0e3c82e0b8ef2f35c6fdf922166161",
"md5": "c5f63e9fbfb1b4722ddcffc5f81dc0ec",
"sha256": "6d470421eb23d35416f037772d72d41dfed6dd8e9c2704b7ea40641eb6a5bf4b"
},
"downloads": -1,
"filename": "icreports-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5f63e9fbfb1b4722ddcffc5f81dc0ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32087,
"upload_time": "2024-12-10T16:34:22",
"upload_time_iso_8601": "2024-12-10T16:34:22.588756Z",
"url": "https://files.pythonhosted.org/packages/2c/7b/a3f5a7d16213f01c38c32293427d7f0e3c82e0b8ef2f35c6fdf922166161/icreports-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6051d46c8d123cece54be841c8be30d2ecdbfe0ce1ef9e132569a281166c996a",
"md5": "859e7654228aad278294ec876b1fc96b",
"sha256": "0e549f4134d40119117002e8af691c4c82c49efa219f4f8723da2d78dd6020fb"
},
"downloads": -1,
"filename": "icreports-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "859e7654228aad278294ec876b1fc96b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 28444,
"upload_time": "2024-12-10T16:34:24",
"upload_time_iso_8601": "2024-12-10T16:34:24.865879Z",
"url": "https://files.pythonhosted.org/packages/60/51/d46c8d123cece54be841c8be30d2ecdbfe0ce1ef9e132569a281166c996a/icreports-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-10 16:34:24",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "icreports"
}
