From 71e71a0c772947b7319d31317776e92bd3e10c85 Mon Sep 17 00:00:00 2001
From: David Rheinsberg <david.rheinsberg@gmail.com>
Date: Mon, 2 Mar 2020 19:29:47 +0100
Subject: [PATCH] docs: add man-page osbuild(1)

This adds a man-page `osbuild(1)` which documents the `osbuild`
executable. We use the python-native doc-utils and rely on
reStructuredText as documentation language.

While it is common with python libraries to use sphinx for documenting
the project, this commit explicitly does not import a full sphinx
documentation. Instead, it only adds the `rst` sources for man-pages.
These can be built by distributions via a simple:

    rst2man docs/<manpage>.rst docs/<output-file>
---
 docs/osbuild.1.rst | 135 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 135 insertions(+)
 create mode 100644 docs/osbuild.1.rst

diff --git a/docs/osbuild.1.rst b/docs/osbuild.1.rst
new file mode 100644
index 00000000..755bb6df
--- /dev/null
+++ b/docs/osbuild.1.rst
@@ -0,0 +1,135 @@
+=======
+osbuild
+=======
+
+----------------------------------------------
+Build-Pipelines for Operating System Artifacts
+----------------------------------------------
+
+:Manual section: 1
+:Manual group: User Commands
+
+SYNOPSIS
+========
+
+| ``osbuild`` [ OPTIONS ] PIPELINE
+| ``osbuild`` [ OPTIONS ] -
+| ``osbuild`` ``--help``
+
+DESCRIPTION
+===========
+
+**osbuild** is a build-system for operating system artifacts. It takes a
+pipeline description as input and produces file-system trees, images, or other
+artifacts as output. Its pipeline description gives comprehensive control over
+the individual steps to execute as part of a pipeline. **osbuild** provides
+isolation from the host system as well as caching capabilities, and thus
+ensures that pipeline builds will be deterministic and efficient.
+
+OPTIONS
+=======
+
+**osbuild** reads the pipeline description from the file passed on the
+command-line. To make **osbuild** read the pipeline description from standard
+input, pass ``-``.
+
+The following command-line options are supported. If an option is passed, which
+is not listed here, **osbuild** will deny startup and exit with an error.
+
+-h, --help                      print usage information and exit immediately
+--build-env=PATH                json file containing a description of the build
+                                environment
+--store=DIR                     directory where intermediary file system trees
+                                are stored
+--sources=PATH                  json file containing a dictionary of source
+                                configuration
+--secrets=PATH                  json file containing a dictionary of secrets
+                                that are passed to sources
+-l, --libdir=DIR                directory containing stages, assemblers, and
+                                the osbuild library
+--checkpoint=CHECKPOINT         stage to commit to the object store during
+                                build (can be passed multiple times)
+--json                          output results in JSON format
+
+PIPELINES
+=========
+
+The build process for an image is described by a pipeline. Each *stage* in a
+pipeline is a program that, given some configuration, modifies a file system
+tree. Finally, an assembler takes a filesystem tree, and assembles it into an
+image. Pipelines are defined as JSON files like this one:
+
+|
+| {
+|   "name": "Example Image",
+|   "stages": [
+|     {
+|       "name": "org.osbuild.dnf",
+|       "options": {
+|         "releasever": "31",
+|         "basearch": "x86_64",
+|         "repos": [
+|           {
+|             "metalink": "https://example.com",
+|             "checksum": "sha256:...<checksum>...",
+|             "gpgkey": "...<gpg-key>..."
+|           }
+|         ],
+|         "packages": [ "@Core", "grub2-pc", "httpd" ]
+|         }
+|     },
+|     {
+|       "name": "org.osbuild.systemd",
+|       "options": {
+|         "enabled_services": [ "httpd" ]
+|       }
+|     },
+|     {
+|       "name": "org.osbuild.grub2",
+|       "options": {
+|         "root_fs_uuid": "76a22bf4-f153-4541-b6c7-0332c0dfaeac"
+|       }
+|     }
+|   ],
+|   "assembler": {
+|     "name": "org.osbuild.qemu",
+|     "options": {
+|       "format": "qcow2",
+|       "filename": "example.qcow2",
+|       "ptuuid": "0x7e83a7ba",
+|       "root_fs_uuid": "76a22bf4-f153-4541-b6c7-0332c0dfaeac",
+|       "size": 3221225472
+|     }
+|   }
+| }
+|
+
+`osbuild` runs each of the stages in turn, isolating them from the host and
+from each other, with the exception that they all operate on the same
+filesystem-tree. The assembler is similarly isolated, and given the same
+tree, in read-only mode, and assembles it into an image without altering
+its contents.
+
+The filesystem tree produced by the final stage of a pipeline, is named
+and optionally saved to be reused as the base for future pipelines.
+
+Each stage is passed the (appended) `options` object as JSON over stdin.
+
+The above pipeline has no base and produces a qcow2 image.
+
+EXAMPLES
+========
+
+ 1. To build a basic qcow2 image of Fedora 30, use:
+
+    ``sudo osbuild --sources samples/sources.json samples/base-qcow2.json``
+
+    Superuser privileges are needed to mount file systems, create loop devices,
+    and setup isolation environments.
+
+ 2. To run **osbuild** from a local checkout, use:
+
+    ``sudo python3 -m osbuild --libdir . --sources samples/sources.json samples/base-qcow2.json``
+
+    This will make sure to execute the `osbuild` module from the current
+    directory, as well as use it to search for stages, assemblers, and more.