Arillso Guide

The simple, flexible, robust and powerful toolbox for Ansible. It contains roles for managing Linux and Windows devices.

The site is published as Sphinx HTML built on top of antsibull-docs. Collection documentation for arillso.system, arillso.agent, and arillso.container is generated from the upstream collections and themed with the custom CSS/JS bundle in _static/.

Source Layout

Path	Purpose
src/	Frontend sources (CSS tokens/base/layout/components, JS feature modules). PostCSS + esbuild emit the bundles into _static/. See src/README.md.
_templates/	Jinja2 overrides for the Sphinx theme, including reusable component macros under _templates/components/.
scripts/	Python and shell helpers — collection_cache.py (collection cache), normalize_collections.py (normalisation pass), build_frontend.sh (frontend bundle).
rst/	Hand-written Sphinx sources plus the generated collection trees that antsibull-docs writes during the build.
_static/	Build artefacts consumed by Sphinx (custom.css, custom.js). Regenerated by the frontend build — do not edit by hand.
tests/	Pytest suite for the build scripts (collection cache, normaliser).
versions.env	Pinned collection versions consumed by build.sh and collection_cache.py.
build.sh	Top-level build entry point — orchestrates the steps below.
conf.py / antsibull-docs.cfg	Sphinx and antsibull-docs configuration.

Local Development

Prerequisites: Python 3.11+, Node.js 20+, and ansible-galaxy on PATH (only needed when the collection cache is cold and you are online).

The repository ships a dde v2 setup, so the simplest path is a containerised build that serves the site behind Traefik on a per-checkout .test hostname:

dde project:up        # build + serve; prints the .test URL

For a host-local build without dde:

# 1. Install Python and Node dependencies
npm ci
pip install -r requirements.txt -r requirements-dev.txt

# 2a. Full build (collections + Sphinx + frontend)
./build.sh

# 2b. Or only rebuild the frontend bundle into _static/
npm run build

To work offline against an already-populated collection cache, set ARILLSO_OFFLINE=1 before invoking ./build.sh. The cache root can be overridden with ARILLSO_COLLECTIONS_CACHE (defaults to ~/.cache/arillso-collections).

Watch mode while editing the frontend:

npm run build:watch:css   # PostCSS, in one shell
npm run build:watch:js    # esbuild, in another shell

Build Steps

./build.sh runs the pipeline in this order:

1. Frontend build — scripts/build_frontend.sh runs PostCSS over src/styles/index.css and esbuild over src/scripts/index.js, writing _static/custom.css and _static/custom.js.
2. Collection cache — scripts/collection_cache.py ensure reads versions.env, populates ~/.cache/arillso-collections/ (offline when ARILLSO_OFFLINE=1), and exports ANSIBLE_COLLECTIONS_PATH.
3. antsibull-docs — generates RST for arillso.system, arillso.agent, arillso.container into temp-rst/, then rsyncs into rst/collections/.
4. Normalisation — scripts/normalize_collections.py --root rst rewrites collection names to the canonical short form.
5. Sphinx — sphinx-build -M html rst build -W --keep-going renders the site into build/html/.
6. PostCSS optimisation — when postcss is on PATH, the produced build/html/_static/custom.css is run through autoprefixer and cssnano for the final minified asset.

Contributing

See CONTRIBUTING.md for development setup, build instructions, and the pull request process.

Further Reading

• src/README.md — frontend module map, token usage, component macros, and frontend build commands.
• docs/regression-checklist.md — manual regression checklist.

License

MIT — see LICENSE.