canonical · cjdcordeiro · Aug 16, 2023 · Jul 17, 2023 · Jul 27, 2023 · Jul 28, 2023
diff --git a/Makefile b/Makefile
@@ -30,6 +30,7 @@ clean: ## Clean artefacts from building, testing, etc.
 	rm -f .coverage
 	rm -rf htmlcov/
 	rm -rf .pytest_cache
+	$(MAKE) -C docs clean
 	rm -rf .mypy_cache
 
 .PHONY: coverage
@@ -41,7 +42,8 @@ coverage: ## Run pytest with coverage report.
 .PHONY: preparedocs
 preparedocs: ## move file from the sphinx-starter-pack to docs folder
 	cp docs/sphinx-starter-pack/.sphinx/_static/* docs/_static
-	cp -R docs/sphinx-starter-pack/.sphinx/_templates docs/_templates
+	mkdir -p docs/_templates
+	cp -R docs/sphinx-starter-pack/.sphinx/_templates/* docs/_templates
 	cp docs/sphinx-starter-pack/.sphinx/spellingcheck.yaml docs/spellingcheck.yaml
 
 .PHONY: installdocs

diff --git a/docs/.wordlist.txt b/docs/.wordlist.txt
@@ -1,77 +1,93 @@
+ACR
+autotools
 Autotools
-CLI
-CMake
+centric
 Charmcraft
-Diátaxis
-Dockerfile
-Dockerfiles
-GID
-GPG
-Kubernetes
-LXD
-Lifecycle
-Multipass
-NGINX
-NGINX's
-NPM
-OCI
-OpenSSL
-OpenSSL's
-Permalink
-PyPI
-ROCK's
-ROCKs
-Rockcraft
-Rockcraft's
-Runtime
-SCons
-SPDX
-SSL
-Skopeo
-Snapcraft
-Snyk's
-UID
-Znet
-autotools
 cli
+CLI
 cmake
+CMake
+CMD
+declaratively
 dev
+Diátaxis
+distroless
 dnf
+Dockerfile
+Dockerfiles
+DockerHub
 dotnet
+ECR
 emacs
 entrypoint
+entrypoints
 executables
 filesystem
 fs
+GID
 github
+GPG
 https
 init
 interoperable
 io
+Kubernetes
 libc
 libssl
 lifecycle
+Lifecycle
 linuxcontainers
 literalinclude
 localhost
+LTS
 lxd
+LXD
+Multipass
 nano
 nginx
+NGINX
+NGINX's
 npm
+NPM
 oci
+OCI
 openssl
+OpenSSL
+OpenSSL's
 organize
 packageName
+Permalink
+PID
+Podman
 pyfiglet
+PyPI
 reStructuredText
 rockcraft
+Rockcraft
+Rockcraft's
+ROCK's
+ROCKs
+runit
+runtime
+Runtime
 scons
+SCons
 skopeo
+Skopeo
 sliceName
 snapcraft
+Snapcraft
+Snyk's
+SPDX
+SSL
 subdir
 subdirectory
 submodules
+subreaping
+supervisord
+tini
 triaged
 ubuntu
+UID
 yaml
+Znet
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -1,28 +1,3 @@
-@import url('https://fonts.googleapis.com/css2?family=Ubuntu:ital@0;1&display=swap');
-
-body {
-    font-family: Ubuntu, "times new roman", times, roman, serif;
-}
-
-div .toctree-wrapper {
-    column-count: 2;
-}
-
-div .toctree-wrapper>ul {
-    margin: 0;
-}
-
-ul .toctree-l1 {
-    margin: 0;
-    -webkit-column-break-inside: avoid;
-    page-break-inside: avoid;
-    break-inside: avoid-column;
-}
-
-.wy-nav-content {
-    max-width: none;
-}
-
 .log-snippets {
     color: rgb(141, 141, 141);
 }
diff --git a/docs/_static/rock_diagram.png b/docs/_static/rock_diagram.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -199,9 +199,14 @@
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)
-html_css_files = ["css/custom.css", "github_issue_links.css", "custom.css"]
+html_css_files = [
+    "css/custom.css",
+    "github_issue_links.css",
+    "custom.css",
+    "header.css",
+]
 
-html_js_files = []
+html_js_files = ["header-nav.js"]
 if "github_issues" in html_context and html_context["github_issues"]:
     html_js_files.append("github_issue_links.js")
 
@@ -213,6 +218,7 @@
 typehints_fully_qualified = False
 always_document_param_types = True
 typehints_document_rtype = True
+linkcheck_anchors_ignore = ["slice-definitions"]
 
 # Enable support for google-style instance attributes.
 napoleon_use_ivar = True

diff --git a/docs/explanation/chisel.rst b/docs/explanation/chisel.rst
@@ -44,3 +44,15 @@ could see as a block of stone from which we can carve and extract only the
 small and relevant parts that we need to run our applications, thus keeping
 ROCKs small and less exposed to vulnerabilities.
 
+Defining slices
+~~~~~~~~~~~~~~~
+
+A package's slices can be defined via a YAML slice definitions file. Check the
+`slice definitions reference
+<https://github.com/canonical/chisel/#slice-definitions>`_ for more information
+about this file's format.
+
+.. note::
+   To find examples of existing slice definitions files, check the Chisel
+   releases repository at `<https://github.com/canonical/chisel-releases>`_.
+   Contributions are welcome and encouraged.
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
@@ -14,3 +14,4 @@ the motivations behind its development.
    chisel
    overlay-step
    rocks
+   pebble
diff --git a/docs/explanation/overlay-step.rst b/docs/explanation/overlay-step.rst
@@ -5,6 +5,8 @@ The component parts of a ROCK are built in a sequence of
 five separate steps: pull, overlay, build, stage and prime.
 
 The overlay step is specific to ROCKs and is configured with overlay parameters.
+To learn more about pull, build, stage and prime see :doc:`/reference/parts`
+
 
 .. Include a section about overlay parameters from the Craft Parts documentation.
 .. include:: /common/craft-parts/overlay_parameters.rst
diff --git a/docs/explanation/pebble.rst b/docs/explanation/pebble.rst
@@ -0,0 +1,87 @@
+.. _pebble_explanation_page:
+
+Pebble
+======
+
+.. important::
+    **Pebble is the default entrypoint for all ROCKs!**
+
+Similar to other well-known process managers such as *supervisord*, *runit*, or
+*s6*, `Pebble`_ is a service manager that enables the seamless orchestration of
+a collection of local service processes as an organised set. The main difference
+is that `Pebble`_ has been designed with custom-tailored features that
+significantly enhance the overall container experience, making it the ideal
+candidate for the container's init process (also known as the entrypoint,
+with PID=1).
+
+Multiple processes in a container?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Containers' best practices advocate the separation of concerns and the adoption
+of a single service per container. With the introduction of `Pebble`_ as the
+ROCKs' entrypoint, this principle is elevated to new heights:
+
+  *if multiple processes rely on shared dependencies and are tightly coupled
+  together (i.e. they serve a single purpose and cannot be executed
+  independently), then the best practice entails orchestrating them within the
+  same container, with Pebble as their manager.*
+
+This new notion addresses existing pain points arising from the excessive
+separation of concerns, which results in numerous container images whose
+entrypoints lack the ability to gracefully handle the underlying child
+processes. This is one of the main reasons behind the gradual shift in the best
+practices, as there is an increasing emphasis on adopting init processes such
+as `tini`_, `s6-overlay`_, or `Pebble`_.
+
+What to expect?
+~~~~~~~~~~~~~~~
+
+Pebble distinguishes itself from other similar tools (like `tini`_ and
+`s6-overlay`_) by offering the following core features:
+
+* **client-server model behind a single binary**: Pebble is injected into
+  ROCKs as a single binary which acts both as a daemon and a client to itself;
+* **declarative service definition**: the Pebble service processes (or simply
+  *Pebble services*) are declaratively defined in YAML files called layers.
+  Compared to `imperative wrapper scripts (as suggested in the Docker
+  documentation)`_, this provides a much cleaner and less error-prone way
+  to define the processes that should run inside the container.
+* **services as first-class citizens**: unlike wrapper scripts, Pebble
+  treats services as manageable units with a defined lifecycle and
+  service-specific definitions for health monitoring, inter-service
+  dependencies, restart policies, and much more;
+* **layering**: Pebble can stack multiple layers (represented as YAML files)
+  into a single Pebble plan where all services are defined. With this layering
+  mechanism, existing services can be overridden or re-configured;
+* **container-optimised init process**: as a ROCK's PID 1, Pebble acts as an
+  init process and thus offers:
+
+  * support for multiple child processes,
+  * reaping and subreaping,
+  * signal forwarding,
+  * graceful shutdown,
+  * log rotation,
+  * run the Pebble daemon and client commands in a single operation;
+* **consistent user experience**: since every ROCK has Pebble as its
+  entrypoint, a predictable and consistent user experience is guaranteed;
+* **embedded utilities**: regardless of the ROCK's contents, Pebble offers a
+  comprehensive suite of commands for inspecting and interacting with the
+  container. These commands are especially useful for :ref:`Chiselled ROCKs
+  <chisel_explanation>`, as they encompass functionalities such as listing and
+  deleting files, creating directories, and inspecting Pebble services,
+  among others.
+
+Creating services
+~~~~~~~~~~~~~~~~~
+
+Rockcraft follows the `Pebble layer specification`_ to the letter, with Pebble
+services defined in :doc:`/reference/rockcraft.yaml`.
+:doc:`/how-to/convert-to-pebble-layer` provides an example of how to
+convert a Docker entrypoint to a Pebble layer.
+
+
+.. _Pebble: https://github.com/canonical/pebble
+.. _tini: https://github.com/krallin/tini
+.. _s6-overlay: https://github.com/just-containers/s6-overlay
+.. _imperative wrapper scripts (as suggested in the Docker documentation): https://docs.docker.com/config/containers/multi-service_container/#use-a-wrapper-script
+.. _Pebble layer specification: https://github.com/canonical/pebble#layer-specification