Migrate the documentation to staging

closes #347

CHANGES/347.doc

@@ -0,0 +1,2 @@
+Migrated the whole documentation to staging. The documentation should be now consumed from the
+unified docs site.

pyproject.toml

@@ -73,6 +73,7 @@ ignore = [
     "dev_requirements.txt",
     "doc_requirements.txt",
     "docs/**",
+    "staging_docs/**",
     "template_config.yml",
     ".ci/**",
     ".github/**",

staging_docs/user/guides/00-import-commit.md

@@ -0,0 +1,94 @@
+# Import Content
+
+Create a new repository by running:
+
+```bash
+pulp ostree repository create --name fedora-iot
+```
+
+## Import a Commit
+
+First, build an image representing one OSTree commit and wait until the process finishes:
+
+```bash
+echo """name = \"fishy-commit\"
+description = \"Fishy OSTree commit\"
+version = \"0.0.1\"
+
+[[packages]]
+name = \"fish\"
+version = \"*\"""" > fishy.toml
+
+sudo composer-cli blueprints push fishy.toml
+sudo composer-cli compose start-ostree fishy-commit fedora-iot-commit --ref fedora/stable/x86_64/iot
+sudo composer-cli compose status
+```
+
+Download the result from the server by issuing:
+
+```bash
+sudo composer-cli compose image ${COMPOSER_TASK_UUID}
+```
+
+Ensure that the downloaded tarball is readable by Pulp and import it:
+
+```bash
+pulp ostree repository import-all --name fedora-iot --file ${IMAGE_TARBALL_C1} --repository_name repo
+```
+
+!!! note
+
+    The argument `repository_name` describes the name of an OSTree repository that is contained
+    within the tarball. The name of a repository created by `composer-cli` defaults to `repo`.
+
+
+## Import more Commits
+
+If there is a need to import additional commits, one can do so by attaching new commits to the last
+commit in the existing repository:
+
+```bash
+echo """name = \"vim-commit\"
+description = \"Vim OSTree commit\"
+version = \"0.0.2\"
+
+[[packages]]
+name = \"vim\"
+version = \"*\"""" > vim.toml
+
+sudo composer-cli blueprints push vim.toml
+```
+
+!!! note
+
+    Through this step, the reader should have distributed the imported repository to enable the
+    `composer-cli` utility to download a parent commit to which more commits are going to be
+    attached. Follow `the publish workflow <publish-workflow>` to learn how to distribute a
+    repository.
+
+
+Set the reference to the parent commit, the URL of a Pulp repository to verify the parent against,
+and monitor the status of the build:
+
+```bash
+sudo composer-cli compose start-ostree vim-commit fedora-iot-commit --ref fedora/stable/x86_64/iot --parent fedora/stable/x86_64/iot --url ${DISTRIBUTION_BASE_URL}
+sudo composer-cli compose status
+```
+
+Download the result from the server by issuing:
+
+```bash
+sudo composer-cli compose image ${TASK_UUID}
+```
+
+Import the downloaded tarball into Pulp:
+
+```bash
+pulp ostree repository import-commits --name fedora-iot --file ${IMAGE_TARBALL_C2} --repository_name repo --ref fedora/stable/x86_64/iot
+```
+
+!!! note
+
+    The OSTree plugin currently supports only repositories with the modern `archive` format. The
+    repository's config file still uses the historical term `archive-z2` to signify such a format.
+

staging_docs/user/guides/01-modify-content.md

@@ -0,0 +1,28 @@
+# Modify Content
+
+Users add existing content to a repository by issuing the following commands:
+
+```bash
+pulp ostree repository ref add --repository foo --name ${REF_NAME} --checksum ${COMMIT_CHECKSUM1}
+pulp ostree repository commit add --repository foo --checksum ${COMMIT_CHECKSUM2}
+pulp ostree repository config add --repository foo --pulp_href ${PULP_HREF_CONFIG}
+```
+
+The added content can be listed by inspecting the latest repository version:
+
+```bash
+pulp ostree repository ref list --repository foo
+pulp ostree repository config list --repository foo --version 1
+```
+
+Similarly, to remove content, one specifies refs and commits that should be removed, like so:
+
+```bash
+pulp ostree repository ref remove --repository foo --name ${REF_NAME} --checksum ${COMMIT_CHECKSUM1}
+pulp ostree repository commit remove --repository foo --checksum ${COMMIT_CHECKSUM2}
+```
+
+!!! note
+
+    Bear in mind that the `ostree` utility may require the `config` file to be present in the
+    published repository as well. Otherwise, the `pull` operations may not be successful.

staging_docs/user/tutorials/00-overview.md

@@ -0,0 +1,35 @@
+# Overview
+
+The Pulp OSTree plugin adds support for managing OSTree repositories. In this section,
+readers will learn more about the concept of mirroring remote repositories and publishing
+them for further client's consumption.
+
+## Features
+
+- **Synchronize** a remote OSTree repository and serve it via Pulp.
+- **Import** new OSTree commits to an existing repository.
+- **Modify** commits and refs within a published repository.
+- **Consume** OSTree content imported to Pulp by leveraging the `ostree` utility.
+
+## Requirements
+
+Usually, it is recommended to instal the following utilities when managing OSTree content:
+
+- [ostree](https://manpages.debian.org/testing/ostree/ostree.1.en.html) - a CLI tool for managing
+  versioned filesystem trees locally
+- [osbuild-composer](https://github.com/osbuild/osbuild-composer) - an HTTP service for building
+  bootable OS disk images
+- [composer-cli](https://osbuild.org/docs/user-guide/introduction) - a tool
+  for use with a WELDR API server, managing blueprints, or building new images
+
+In this documentation, these utilities are used to demonstrate the way how to create and consume
+the OSTree content as well as how they can complement the Pulp's functionality.
+
+For the best user experience, the workflows utilize [Pulp CLI OSTree](https://github.com/pulp/pulp-cli-ostree).
+Install the CLI for the OSTree plugin and update its configuration if necessary. It is simple!
+
+```bash
+pip install pulp-cli-ostree
+
+pulp config create && pulp config edit  # configure the reference to the running Pulp instance
+```

staging_docs/user/tutorials/01-sync-and-host.md

@@ -0,0 +1,99 @@
+# Mirror and Host Content
+
+In this tutorial, there is demonstrated how one can mirror remote content into a local Pulp
+repository.
+
+Users can populate their repositories with content from external sources by syncing a remote
+repository. The procedure is as follows: first, create a repository object, then establish a
+remote object pointing to the external source, and finally execute a sync task. Upon completion
+of the sync task, the content is ready to be promoted/published and becomes visible to end users.
+
+## Create a Repository
+
+Start by creating a new repository named "foo".
+
+```bash
+pulp ostree repository create --name foo
+```
+
+## Create a Remote
+
+Then, create a remote object that informs Pulp about an external content source.
+
+```bash
+pulp ostree remote create --name bar --url https://fixtures.pulpproject.org/ostree/small/
+```
+
+Optionally, use the standard Linux wildcards `*`, `?` to include or exclude specific commits from
+a remote repository. This might be helpful when there is no need to mirror everything from the
+remote repository. Besides that, it reduces the network or storage overhead.
+
+```bash
+pulp ostree remote create --name bar-filtered --url https://fixtures.pulpproject.org/ostree/small/ --include-refs "[\"stable\"]" --exclude-refs "[\"raw*\"]"
+```
+
+## Sync the Repository
+
+After creating the repository and remote, use these objects to kick off a synchronization task.
+This tells Pulp to fetch content from the remote source and add it to the repository.
+
+```bash
+pulp ostree repository sync --name foo --remote bar
+```
+
+!!! note
+
+    The OSTree plugin currently supports only repositories with the modern `archive` format. The
+    repository's config file still uses the historical term `archive-z2` to signify such a format.
+
+## Host Content (Create a Distribution)
+
+To serve the OSTree content from Pulp, the user needs to create a distribution that will host the
+associated repository at `${PULP_BASE_ADDR}/pulp/content/<distribution.base_path>`:
+
+```bash
+pulp ostree distribution create --name fedora-iot --base-path fedora-iot --repository fedora-iot
+```
+
+The content present in the latest repository version is automatically published and accessible by
+package managers (e.g., the `ostree` utility).
+
+
+## Consume the Content
+
+Now, configure a local OSTree repository to consume the content from the Pulp repository.
+
+=== "Script"
+
+    ```bash
+    ostree --repo=repo init --mode=archive
+    ostree --repo=repo remote --no-gpg-verify add pulpos ${PULP_BASE_ADDR}/pulp/content/fedora-iot
+
+    ostree pull --repo=repo --mirror pulpos:fedora/stable/x86_64/iot --depth=-1
+    ostree log --repo=repo fedora/stable/x86_64/iot
+    ```
+
+=== "Output"
+
+    ```
+    commit 9bbeb2f9961b425b70551b91992e4e3169e7c695f93d99b03e3f2aac463231bf
+    Parent:  50aeff7f74c66041ffc9e197887bfd5e427248ff1405e0e61e2cff4d3a1cecc7
+    ContentChecksum:  237941566711d062b8b73d0c2823225d59c404d78bf184243c6031fa279e8a1f
+    Date:  2021-09-06 15:48:13 +0000
+    (no subject)
+
+    commit 50aeff7f74c66041ffc9e197887bfd5e427248ff1405e0e61e2cff4d3a1cecc7
+    ContentChecksum:  10155b85154b87675970fd56c4a3b44c4739b486772926ed7463f1c827e7a236
+    Date:  2021-09-06 11:35:16 +0000
+    (no subject)
+    ```
+
+!!! note
+
+    The plugin automatically generates static deltas for a specific subset of commits. Currently,
+    the summary file is not being updated after every single change to the repository.
+
+Users are allowed to copy and remove content within repositories. When a new ref is being added or
+removed from a repository, all the referenced commits and file objects will be added or removed as
+well in order to preserve the integrity of the repository. Visit the guide section to learn more
+about particular workflows.