Merge pull request #28 from isbm/isbm-docs-setup

Add documentation and integrate with the readthedocs.io

.gitignore

@@ -1,3 +1,5 @@
 .vscode/
 /target
-tmp/
+tmp/
+docs/_build/*
+docs/_static/*

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,12 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,22 @@
+project = 'Mezzotint'
+copyright = '2023, Bo Maryniuk'
+author = 'Bo Maryniuk'
+version = "0.1"
+release = "Pre-release"
+
+extensions = [
+    "myst_parser",
+    "sphinx_rtd_theme",
+]
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+html_show_sourcelink = False
+html_static_path = ['_static']
+html_theme = "sphinx_rtd_theme"

docs/contributing.rst

@@ -0,0 +1,35 @@
+.. note::
+
+   This document describes the development process of Mezzotint tool.
+
+Contributing
+============
+
+It's as simple as that: every input matters as a contribution, including your candid subjective feedback `(just don't overdo it)`.
+
+Although Mezzotint is coded in Rust, if you're not comfortable developing in this language, you can still significantly contribute to the project by using it and reporting any encountered issues:
+
+- Features, those are still missing
+- Bug reports and failures it produces
+- Corner cases where it still fails
+
+Developing
+----------
+
+If you're looking to create a new feature, the optimal workflow would be this:
+
+1. Open an issue as a feature you want to have
+2. Let's discuss it there to shape out how it will look like
+3. You implement it and make a Pull Request
+
+Tooling
+-------
+
+If you haven't learned subjectively `world-best editor <https://www.gnu.org/s/emacs>`__ just yet, then alternatively the Visual Studio Code would also do for you.
+
+Assuming you are going to use VSC, install `Rust Analyser <https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer>`__ extension and everything it requires (``rustc``, ``cargo``, ``rustup`` etc). Furthermore, please configure your Visual Studio to automatically reformat your file using the default Rust formatter whenever you save it.
+
+Links
+-----
+
+To open an issue on GitHub, please go `here <https://github.com/isbm/mezzotint/issues>`__, and to open a Pull Request please navigate `here <https://github.com/isbm/mezzotint/pulls>`__.

docs/index.rst

@@ -0,0 +1,85 @@
+.. Teabox documentation master file, created by
+   sphinx-quickstart on Fri Nov 25 14:06:47 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Mezzotint documentation!
+==================================
+
+.. note::
+   This documentation covers Mezzotint |version| — the solution to
+   convert a container (OCI or any other type) into an app-bundle,
+   leaving behind unnecessary "dead code" — libraries that are never
+   really used.
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   installation
+   quickstart
+   usage
+   manpage
+   contributing
+
+
+Concept
+-------
+
+Mezzotint is an alternative solution to `Canonical Chisel <https://github.com/canonical/chisel>`__ tool.
+
+Same as Chisel tool, Mezzotint is also designed to drop unnecessary libraries and files from a container, thus minimising its overall size and convert a typical OCI container to be close as application bundle, keeping  isolation and scalability features.
+
+Content of a container is expected to be provisioned from a package repository and have a clear structure of package dependencies. Its content is specified in a profile as a short set of rules.
+
+However, in contrast to Canonical's Chisel, Mezzotint:
+
+- Designed to be distribution-agnostic, as long as a distribution is using a package manager.
+- Does not need a carefully maintained `database of package descriptions <https://github.com/canonical/chisel-releases>`__, which has to be specific to a particular Linux distribution version.
+- Released under Apache 2.0 licence.
+
+Essentially, Mezzotint is trying to `actually` follow the point of Michelangelo, removing everything unnecessary from a block of marble to make a statue. Both Chisel and Mezzotint tools facing the same pain point in their approach: not everything that is linked needs to be linked, and not everything that is packaged and thus is as a dependency, should be there in certain cases. And to figure-out what is needed and what is not needed — is not the easiest task to do it manually.
+
+.. attention::
+
+   Mezzotint is in its early continuous development phase and should be considered as **experimental software**.
+
+
+Use Cases
+---------
+
+Mezzotint use case is pretty simple, coined by a French writer, poet, journalist and pioneering aviator:
+
+.. hint::
+
+   *A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.*
+
+   — Antoine de Saint-Exupery
+
+Mezzotint should be able to be used in:
+
+- containers
+- embedded Linux images
+- immutable systems
+
+As software developes, these features will come to true one day, but with your Pull Requests, ideas and other contributions even faster! 😃
+
+Limitations
+-----------
+
+1. Mezzotint currently works only with containers of OCI standard. However, there are plans to expand it to the actual provisioned images.
+2. At the moment integration with a package manager is implemented only for Debian package manager, covering only "Debian family" distributions, such as Ubuntu, Mint, Debian itself etc
+3. It is tested only on Ubuntu LTS 22.04 so far
+
+.. sidebar:: Links
+
+   * `GitHub Repository <https://github.com/isbm/mezzotint>`__
+
+   * `GitHub Issues Tracker <https://github.com/isbm/mezzotint/issues>`__
+
+Contributing
+-------------
+
+Best way to make progress is to open an issue (great 👍) or submit a Pull Request (awesome 🤩) on the GitHub.
+
+And just in case you don't know how to implement it in Rust, but you still want something cool to happen, then please fill-in an issue using issue tracker.

docs/installation.rst

@@ -0,0 +1,40 @@
+Installation
+============
+
+.. note::
+    This document describes how to install Mezzotint tool on your machine.
+
+
+Given that the Mezzotint tool is currently in its early stages of development, it requires manual compilation at this time. In the future, plans are underway to facilitate easier installation through various methods, including integration with package managers for a specific distribution of your choice. However, this feature is scheduled for a later phase of development.
+
+Compilation From the Sources
+----------------------------
+
+The following process was tested on Ubuntu 22.04 LTS:
+
+- Ensure the these software components are installed on your system:
+
+  1. `make` (GNU Make)
+  2. `rustc` (Rust, version 1.73.0)
+  3. `cargo`
+  4. `rustup` (Rust installation framework, version 1.26.0)
+
+- Clone the repository:
+
+  .. code-block:: shell
+
+    git clone https://github.com/isbm/mezzotint
+
+- Change directory to the newly created:
+
+  .. code-block:: shell
+
+    cd mezzotint
+
+- Run command:
+
+  .. code-block:: shell
+
+    make release
+
+- If you set it all up correctly, it should compile. Then navigate to ``target/release`` and copy ``mezzotint`` binary anywhere you want (typically ``/usr/bin``).

docs/manpage.rst

@@ -0,0 +1,47 @@
+.. note::
+
+    This is the manpage of Mezzotint tool
+
+
+Manpage
+=======
+
+Usage of Mezzotint as follows:
+
+.. code-block:: text
+
+    Usage: mezzotint [OPTIONS] [FILTERS]
+
+Options
+-------
+
+The following options are available:
+
+-x, --exe <exe>          Specify path to an executable which needs to be preserved
+-p, --profile <profile>  Profile, describing whole setup
+-k, --pkgs <packages>    Comma-separated list of packages to account
+-i, --invert             Invert filters behaviour
+-t, --dry-run            Do not remove anything, only display what will be removed
+-a, --autodeps <mode>    Auto-add package dependencies. `NOTE: This can increase the size, but might not always be useful` Default value is set to `none`. Other possible values: `free`, `clean`, `tight` and default `none`.
+-r, --root <root>        Root filesystem, e.g. mountpoint of an image
+
+Filters
+-------
+
+Filters are used to set what kind of data `type` needs to be filtered out, i.e. removed from the target:
+
+--l10n  Leave localisation data
+--i18n  Leave internationalisation data
+--doc   Leave documents, texts, licences etc
+--man   Leave manpages
+--dirs  Leave empty directories (except required)
+--logs  Leave any kind of logs
+--pic   Leave any graphics (pictures)
+--arc   Leave any kind of archives/tarballs
+
+Other options
+-------------
+
+-d, --debug    Set debug mode for more verbose output.
+-h, --help     Display help
+-v, --version  Get current version.

docs/overview.rst

@@ -0,0 +1,66 @@
+.. overview:
+
+Overview
+========
+
+.. note:: **Abstract**
+
+    What is a container and what is the difference between an app-bundle? How did we came to the point where our containers are as big as the operating systems for just one application?
+
+.. toctree::
+    :maxdepth: 1
+
+    overview/workflow
+
+
+Containers vs App Bundles
+-------------------------
+
+What is a Container?
+^^^^^^^^^^^^^^^^^^^^
+
+A Linux container is a *lightweight*, isolated environment that contains a user-space operating system environment. This way it packages software with all its dependencies so that the application runs quickly and reliably from one computing environment to another.
+
+What is an application bundle?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+An application bundle is a way of organizing related resources, such as an application’s executable and its graphics, into a single directory that appears as a single file to the user. This makes it easier to distribute and install applications, as well as to manage their dependencies and updates.
+
+
+Key Differences
+---------------
+
+The following table roughly explains a typical difference between an application bundles and a containers:
+
+Purpose
+^^^^^^^
+
+An **Application Bundle**, like those on macOS, is a packaging format primarily used for organizing and distributing applications on a specific operating system (in this case, macOS). It contains all the necessary files and resources required to run the application on that particular OS.
+
+A **Linux Container** is a lightweight, portable, and self-sufficient environment that encapsulates an application along with its dependencies, libraries, and runtime components. It enables an application to run consistently across various computing environments.
+
+Isolation
+^^^^^^^^^
+
+An **Application Bundle** doesn't inherently provide isolation. It's meant to organize files and resources but doesn't necessarily isolate the application from the rest of the system.
+
+**Containers**, however, leverage kernel-level isolation features of the Linux operating system to create isolated environments. They offer a higher level of isolation compared to application bundles, allowing applications to run independently without interfering with other applications or the host system.
+
+Portability
+^^^^^^^^^^^
+
+**Application Bundles** are primarily designed for specific operating systems. For instance, MacOS application bundles are specific to those systems and won't run natively on other operating systems without compatibility layers or emulation.
+
+**Linux Container** are a bit more portable, in a way. Once created, a container can run on any system that supports the containerization technology (like Docker or Kubernetes), running a compatible kernel underneath. This means a containerized application can possibly run on various Linux distributions and even on other operating systems such as like Windows or `FreeBSD <https://productionwithscissors.run/2022/09/04/containerd-linux-on-freebsd/>`__.
+
+Resource Sharing
+^^^^^^^^^^^^^^^^
+
+Resources in an **Application Bundle** are contained within the bundle itself and are not typically shared with other applications.
+
+**Containers** can share resources with the host system or other containers, depending on how they are configured. This sharing can include network resources, storage, or even the kernel, which allows for more efficient resource utilization.
+In summary, an application bundle is a packaging format for organizing and distributing applications on a specific operating system, while a Linux container is a technology for creating lightweight, isolated environments that can run applications independently across different systems.
+
+The Final Goal
+--------------
+The goal of the Mezzotint is to combine the best of both worlds into one package.

docs/overview/workflow.rst

@@ -0,0 +1,25 @@
+General Workflow with OCI Containers
+====================================
+
+.. note:: **Abstract**
+
+    Typical workflow when working with OCI containers.
+
+An OCI container (in a nutshell), is usually a complete installation of a complete minimal Linux system within a directory, distributed as a tarball and then mounted somewhere. That directory usually contains many userland bits of the operational root filesystem also contains the basic configuration of the application. Additionally, it contains exported mounted directories elsewhere etc.
+
+The creation process of a container depends on the tooling used, such as Buildah or Docker etc. Mezzotint does not creates the containers, but shreds their "fat" away. 😜
+
+
+Requirements
+============
+
+
+Profile
+-------
+
+Mezzotint employs a YAML-based profile comprising a sequence of directives. These directives encompass specifications like which packages to retain, the filtering or preservation of content types, the criteria for retaining or explicitly removing specific data regardless of circumstances, and more. However, these directives are entirely optional, as Mezzotint primarily operates in an automatic mode, adept at determining most configurations without explicit instructions.
+
+Command Line
+------------
+
+In addition to using a profile, users have the option to manually define all settings through the command line. Yet, this method can be cumbersome and less efficient for repetitive tasks. While employing command line options is not typically the favoured approach due to the abundance of settings, it could prove beneficial when incorporating Mezzotint into a Bash script.