From 0007555880ea9fc875d61ddee3538ab4d9d3f9c1 Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Mon, 8 Dec 2025 20:18:32 -0500 Subject: [PATCH 1/5] docs: replace images with text in mode-of-operation (fixes #31) --- docs/explanation/mode-of-operation.md | 106 +++++--------------------- 1 file changed, 20 insertions(+), 86 deletions(-) diff --git a/docs/explanation/mode-of-operation.md b/docs/explanation/mode-of-operation.md index 6fa067e..1e0869b 100644 --- a/docs/explanation/mode-of-operation.md +++ b/docs/explanation/mode-of-operation.md @@ -2,97 +2,31 @@ # How Chisel works -The purpose of Chisel is to create a minimal Ubuntu root file system comprising -only the application and its runtime dependencies. Chisel is especially useful -for developers who are looking to create minimal and distroless-like container -images. +Chisel uses the {{cut_cmd}} to _slice_ Ubuntu packages, as described in the workflow below: -Chisel uses the {{cut_cmd}} to _slice_ Ubuntu packages, as depicted in the workflow below: +1. **Read and parse chisel-releases** - - - - - + Chisel fetches, reads and validates the {ref}`chisel-release`. + This includes parsing the {ref}`chisel_yaml_ref` and {ref}`slice + definitions` while validating the release and checking for conflicting paths across packages. - - - - - + Chisel groups and merges all slice definitions per package. Then, + for every package, it extracts the **specified slices' paths** into + the provided root file system. +4. **Run mutation scripts and remove temporary files** - - - - - - - - - - - - - - - - - -
+2. **Talk to Ubuntu archives and fetch packages** -```{image} /_static/MO-1.svg - :align: center - :alt: Read and parse chisel-releases -``` + Chisel talks to the {ref}`chisel_yaml_format_spec_archives` directly. + It fetches, validates and parses their `InRelease` files. + It then resolves which archive holds the **requested** packages and fetches + the corresponding package tarballs. - +3. **Install only the specified files from the packages** -Chisel fetches, reads and validates the {ref}`chisel-release`. -This includes parsing the {ref}`chisel_yaml_ref` and {ref}`slice -definitions` while validating the release and checking for conflicting paths across packages. - -
- -```{image} /_static/MO-2.svg - :align: center - :alt: Talk to archives and fetch packages -``` - - - -Chisel talks to the {ref}`chisel_yaml_format_spec_archives` directly. -It fetches, validates and parses their `InRelease` files. -It then resolves which archive holds the **requested** packages and fetches -the corresponding package tarballs. - -
- -```{image} /_static/MO-3.svg - :align: center - :alt: Install package slices -``` - - - -Chisel groups and merges all slice definitions per package. Then, -for every package, it extracts the **specified slices' paths** into -the provided root file system. - -
- -```{image} /_static/MO-4.svg - :align: center - :alt: Run mutation scripts -``` - - - -Chisel then runs the {{mutation_scripts}}. Only the -{ref}`mutable` files may be -modified at this stage. Finally, the files specified with -{ref}`until:mutate` are -removed from the provided root file system. - - -
+ Chisel then runs the {{mutation_scripts}}. Only the + {ref}`mutable` files may be + modified at this stage. Finally, the files specified with + {ref}`until:mutate` are + removed from the provided root file system. From dc7eb00a81300fb4aa03846ef81dda3dd52aa7aa Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Mon, 15 Dec 2025 13:01:55 -0500 Subject: [PATCH 2/5] docs: replace images with mermaid diagrams --- docs/explanation/mode-of-operation.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/explanation/mode-of-operation.md b/docs/explanation/mode-of-operation.md index 1e0869b..279e1a7 100644 --- a/docs/explanation/mode-of-operation.md +++ b/docs/explanation/mode-of-operation.md @@ -2,7 +2,27 @@ # How Chisel works -Chisel uses the {{cut_cmd}} to _slice_ Ubuntu packages, as described in the workflow below: +Chisel uses the {{cut_cmd}} to _slice_ Ubuntu packages, following the workflow below: + +```mermaid +graph TD + %% Define the nodes with the Hexagon shape + step1{{1. Read and parse chisel-releases}} + step2{{2. Talk to Ubuntu archives
and fetch packages}} + step3{{3. Install only the specified
files from packages}} + step4{{4. Run mutation scripts and
remove temporary files}} + + %% Connect the nodes + step1 --> step2 + step2 --> step3 + step3 --> step4 + + %% Style the nodes to match the original Chisel red + style step1 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white + style step2 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white + style step3 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white + style step4 fill:#a81c1c,stroke:#333,stroke-width:1px,color:white + ``` 1. **Read and parse chisel-releases** From 2d137c367ef4f3a41a93ad0bdcfdd12de993f97d Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Wed, 17 Dec 2025 20:37:12 -0500 Subject: [PATCH 3/5] build: fix mermaid diagrams rendering --- docs/conf.py | 8 +++++++- docs/requirements.txt | 1 + 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 1d93b77..17486f9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -266,10 +266,15 @@ # substitution, deflist, linkify myst_enable_extensions = set( - ["substitution", "deflist", "linkify", "tasklist", "attrs_inline"] + ["substitution", "deflist", "linkify", "tasklist", "attrs_inline", "colon_fence"] ) +# Fix: Tell MyST to treat "mermaid" code blocks as a directive, +# preventing the "Pygments lexer name 'mermaid' is not known" warning. +myst_fence_as_directive = ["mermaid"] + + # Custom Sphinx extensions; see # https://www.sphinx-doc.org/en/master/usage/extensions/index.html @@ -295,6 +300,7 @@ "sphinx_last_updated_by_git", "sphinx.ext.intersphinx", "sphinx_sitemap", + "sphinxcontrib.mermaid", ] # Excludes files or directories from processing diff --git a/docs/requirements.txt b/docs/requirements.txt index 4bde8aa..be87962 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -26,6 +26,7 @@ packaging sphinxcontrib-svg2pdfconverter[CairoSVG] sphinx-last-updated-by-git sphinx-sitemap +sphinxcontrib-mermaid # Vale dependencies rst2html From c4f845c1183f570891e49e8150fada43d953668d Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Wed, 17 Dec 2025 20:43:54 -0500 Subject: [PATCH 4/5] docs: remove obsolete image files --- docs/_static/MO-1.svg | 1 - docs/_static/MO-2.svg | 1 - docs/_static/MO-3.svg | 1 - docs/_static/MO-4.svg | 1 - 4 files changed, 4 deletions(-) delete mode 100644 docs/_static/MO-1.svg delete mode 100644 docs/_static/MO-2.svg delete mode 100644 docs/_static/MO-3.svg delete mode 100644 docs/_static/MO-4.svg diff --git a/docs/_static/MO-1.svg b/docs/_static/MO-1.svg deleted file mode 100644 index c363f5b..0000000 --- a/docs/_static/MO-1.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/_static/MO-2.svg b/docs/_static/MO-2.svg deleted file mode 100644 index e24a904..0000000 --- a/docs/_static/MO-2.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/_static/MO-3.svg b/docs/_static/MO-3.svg deleted file mode 100644 index de46494..0000000 --- a/docs/_static/MO-3.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/_static/MO-4.svg b/docs/_static/MO-4.svg deleted file mode 100644 index 43991b0..0000000 --- a/docs/_static/MO-4.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file From 78a1f2a026ad99e0e0685003eb98aa4538d5198b Mon Sep 17 00:00:00 2001 From: Chandrahas Maddineni Date: Tue, 6 Jan 2026 16:21:08 -0500 Subject: [PATCH 5/5] Fix mermaid diagram height issue causing large gaps --- docs/_static/custom.js | 20 ++++++ docs/conf.py | 5 ++ docs/explanation/mode-of-operation.md | 93 +++++++++++++-------------- 3 files changed, 70 insertions(+), 48 deletions(-) create mode 100644 docs/_static/custom.js diff --git a/docs/_static/custom.js b/docs/_static/custom.js new file mode 100644 index 0000000..2671444 --- /dev/null +++ b/docs/_static/custom.js @@ -0,0 +1,20 @@ +/** + * Fix for mermaid diagram SVG height issue. + * + * The mermaid extension generates inline