docs: Rewrite the explanation section

This PR add the explanation of Pebble and
rewrite chisel,rocks and overlay-step explanation.
Co-authored-by: Cristovao Cordeiro <[email protected]>

docs/.wordlist.txt

@@ -1,11 +1,16 @@
+ACR
 Charmcraft
 cli
 CLI
+CMD
 dev
 Diátaxis
 Dockerfile
 Dockerfiles
+DockerHub
+ECR
 entrypoint
+entrypoints
 filesystem
 fs
 GID
@@ -23,6 +28,7 @@ Lifecycle
 linuxcontainers
 literalinclude
 localhost
+LTS
 lxd
 LXD
 Multipass
@@ -36,66 +42,7 @@ OpenSSL
 OpenSSL's
 packageName
 Permalink
-pyfiglet
-PyPI
-reStructuredText
-rockcraft
-Rockcraft
-Rockcraft's
-ROCK's
-ROCKs
-Runtime
-skopeo
-Skopeo
-sliceName
-snapcraft
-Snapcraft
-Snyk's
-SPDX
-SSL
-ubuntu
-UID
-yaml
-Znet
-samir@samir-Laptop:~/Desktop/Github-Repo/rockcraft/docs$ sort .wordlist.txt
-Charmcraft
-cli
-CLI
-dev
-Diátaxis
-Dockerfile
-Dockerfiles
-entrypoint
-filesystem
-fs
-GID
-github
-GPG
-https
-init
-interoperable
-io
-Kubernetes
-libc
-libssl
-lifecycle
-Lifecycle
-linuxcontainers
-literalinclude
-localhost
-lxd
-LXD
-Multipass
-nginx
-NGINX
-NGINX's
-oci
-OCI
-openssl
-OpenSSL
-OpenSSL's
-packageName
-Permalink
+Podman
 pyfiglet
 PyPI
 reStructuredText

docs/explanation/chisel.rst

@@ -12,6 +12,16 @@ needed for the ROCK to function properly.
 
 See :ref:`how_to_use_chisel` for information about using the tool.
 
+Slice definitions
+-----------------
+
+A slice is a yaml file permitting chisel to slice the package,
+`here <https://github.com/canonical/chisel#slice-definitions>`_ is
+the slice definition reference.
+
+To find more examples or if you want to contribute,
+check `chisel-releases <https://github.com/canonical/chisel-releases>`_.
+
 Package slices
 --------------
 

docs/explanation/index.rst

@@ -14,3 +14,4 @@ the motivations behind its development.
    chisel
    overlay-step
    rocks
+   pebble

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
+.. include:: /common/craft-parts/overlay_parameters.rst

docs/explanation/pebble.rst

@@ -0,0 +1,36 @@
+.. _pebble_explanation_page:
+
+Pebble
+======
+
+Pebble is a service manager that helps to organise a set of local service 
+processes.
+
+When creating container images, several issues can be met.
+For instance, if the entrypoint relies on the application mode
+(such as nginx and nginx-debug), creating a bash script that parses all the
+arguments provided during container deployment will be necessary.
+Additionally, each image runs with specific application arguments,
+making it challenging to perform an inspection inside the image consistently.
+
+Pebble solves these problems by providing a comprehensive set of commands
+for starting, stopping, and viewing service status. It also includes features
+like auto-restart for continuous operation and dependency management for
+properly sequencing services. Pebble streamlines service management as a
+single binary that operates as a background service and a client.
+
+In ROCKs, Pebble services are defined with properties such as name, command,
+startup behaviour, dependencies,... Moreover, Pebble is the default entrypoint
+(an executable that runs when the container is initiated) in ROCKs, ensuring
+consistent container inspection and permit to have multiple entrypoint
+without the need to create other files.
+
+
+Create a service
+----------------
+
+See :doc:`/how-to/convert-to-pebble-layer` for information about converting
+a Docker entrypoint to a pebble service. Also, check the top-level field
+on :doc:`/reference/rockcraft.yaml` to understand the parameters and fields
+needed to create a service.
+

docs/explanation/rocks.rst

@@ -3,22 +3,61 @@
 ROCKs
 =====
 
-ROCKs are container images that are compliant with the `Open Container
-Initiative`_ (OCI) `image format specification <OCI_image_spec_>`_.
-This means that ROCKs are interoperable with other tools that work with
-OCI-compliant images.
+ROCKs are Ubuntu-based container images that are designed to meet
+cloud-native software's security, stability, and reliability requirements.
 
-A ROCK can be stored in an existing container registry, very much like any
-Docker image, and run in the same way as any other container image.
-For example, Docker can be used to run a ROCK with the usual command line
-syntax:
+ROCKs were created with a focus on those values:
 
-.. code:: bash
+* **Developers experience**: Rockcraft uses a declarative format to describe ROCKs, 
+  aiming to simplify container image definition and provide the best user experience.
+* **Ubuntu Experience**: Built on top of Ubuntu, ROCKs provide reliability 
+  and stability to users. They offer access to the latest features, ensuring 
+  users can meet their needs. With long-term support (LTS), ROCKs images 
+  are regularly updated.
+* **Consistency**: ROCKs are consistent by utilising Pebble as the entrypoint.
+  Learning Pebble allows you to interact smoothly with all the ROCKs.
 
-   docker run <rock> ...
+ROCKs comply with the `Open Container
+Initiative`_ (OCI) `image format specification <OCI_image_spec_>`_.
+ROCKs can be stored in container registries (e.g. DockerHub, ECR, ACR,..)
+and used with any OCI-Compliant tools (e.g. Docker, Podman, Kubernetes,...).
 
-Interoperability between ROCKs and other containers also extends to the way
-that container images are built. This enables the use of ROCKs as bases for
+Interoperability between ROCKs and other containers also extends to how
+container images are built. This enables using ROCKs as bases for
 existing build recipes, such as Dockerfiles, for further customisation and
 development.
 
+The ROCKs ecosystem comprises
+
+.. figure:: /_static/rockcraft_diagram.jpg
+   :width: 75%
+   :align: center
+   :alt: ROCKs ecosystem
+
+
+Chisel
+------
+
+Chisel is a software tool for extracting well-defined portions
+(also known as slices)  of Debian packages into a filesystem.
+To learn more about Chisel see: :ref:`chisel_explanation`
+
+Pebble
+------
+
+In ROCKS, Pebble is the default entrypoint (an executable that
+runs when the container is initiated) in ROCKS, ensuring consistent
+container inspection and permit to have multiple entrypoint
+without the need to create other files.To learn more about
+Pebble see: :ref:`pebble_explanation_page`
+
+Rockcraft
+---------
+
+Rockcraft is a tool designed to build ROCKs using a declarative syntax
+(yaml). It leverages the logic of plugins, parts,and concepts that exist
+in Snapcraft and Charmcraft.
+
+Developers familiar with the creation and publication of snaps and charms
+will be able to utilise existing knowledge to create ROCKS.
+To learn why you need to use Rockcraft see: :ref:`why_use_rockcraft`