fixup! Rework the workflow docs

docs/workflows.rst

@@ -13,5 +13,6 @@ Any workflows that cannot be achieved via Pulp CLI, will use ``httpie`` to talk
    workflows/sync
    workflows/upload
    workflows/publish
+   workflows/signing_service
    workflows/advanced_copy
    workflows/checksums

docs/workflows/publish.rst

@@ -3,6 +3,8 @@
 Hosting APT Repositories
 ================================================================================
 
+.. include:: ../external_references.rst
+
 .. figure:: publish.svg
    :alt: Publish content
 
@@ -12,10 +14,43 @@ Hosting APT Repositories
 Basic Workflow
 --------------------------------------------------------------------------------
 
+Once you have obtained some ``pulp_deb`` content, either via :ref:`sync <workflows_sync>` or :ref:`upload <upload_and_manage_content>`, that content must then be published and distributed so as to be available for clients.
+The most basic version of this workflow is always the same, and all you need is the name of the relevant Pulp repository:
+
+.. code-block:: bash
+
+   pulp deb repository list
+   NAME=my-repository  # Insert some repository name from the list here.
+   pulp deb publication create --repository=${NAME}
+   pulp deb distribution create --name=${NAME} --base-path=${NAME} --repository=${NAME}
+
+Creating the distribution will return the ``base_url`` in the API response, which will contain the URL to your hosted repository.
+The ``base_url`` has the following structure:
+
+.. code-block:: none
+
+   <CONTENT_ORIGIN><CONTENT_PATH_PREFIX><distribution_base_path>
+
+- ``CONTENT_ORIGIN`` is a required pulpcore setting, containing the protocol, fqdn, and port where the content app is reachable.
+  See also the `pulpcore settings documentation`_.
+- ``CONTENT_PATH_PREFIX`` is a optional pulpcore setting that defaults to ``/pulp/content/``.
+- The distribution base path is what you have supplied to the ``--base-path`` flag in the above example.
+  In the examples in this documentation, we generally just use the repository name for the base path as well, but you may want to depart from that convention.
+
+An example ``base_url`` could be:
+
+.. code-block:: none
+
+   http://my-pulp-instance.com:5001/pulp/content/my-repository/
+
 
 Metadata Signing
 --------------------------------------------------------------------------------
 
+.. attention::
+  This workflow assumes you have already created a signing service of type ``AptReleaseSigningService``.
+  See the workflow on :ref:`signing service creation <workflows_signing_service>` for how to do this.
+
 
 Verbatim Publications
 --------------------------------------------------------------------------------

docs/workflows/signing_service.rst

@@ -0,0 +1,48 @@
+.. _workflows_signing_service:
+
+Signing Service Creation
+================================================================================
+
+To sign your APT release files on your ``pulp_deb`` publications, you will first need to create a signing service of type ``AptReleaseSigningService``.
+
+
+Prerequisites
+--------------------------------------------------------------------------------
+
+Creating a singing service requires the following pieces of information:
+
+- A unique name for the signing service, use ``pulp signing-service list --field=name`` to see what has been taken already.
+- The public key fingerprint of the GPG key that the signing service should use for signing.
+  The public key itself must be available in the pulp user's GPG home directory.
+- A path to a signing script or executable that must meet the following criteria:
+
+  - Must be executable by the user pulp is running as.
+  - Must be available on each pulp worker.
+  - When a path to a file that is to be signed, e.g.: ``/tmp/LJDSFHD/Release`` is passed to the executable, it must return a JSON dict like the following:
+
+    .. code-block:: json
+
+       {
+           "signatures": {
+                "inline": "/tmp/LJDSFHD/InRelease",
+                "detached": "/tmp/LJDSFHD/Release.gpg",
+           }
+       }
+
+    Here, either ``inline`` or ``detached`` may be omitted but we recommend creating both.
+    In addition, the values for ``inline`` and ``detached`` must be the path to a file, that can be verified against the input file using the GPG key associated with the signing service.
+
+
+Example Signing Script
+--------------------------------------------------------------------------------
+
+The following example signing service script is used as part of the ``pulp_deb`` test suite:
+
+.. literalinclude:: ../../pulp_deb/tests/functional/sign_deb_release.sh
+   :language: bash
+
+It assumes that both public and secret key for ``GPG_KEY_ID="Pulp QE"`` is present in the GPG home of the Pulp user and that the secret key is not protecteded by a password.
+
+
+Creation Workflow
+--------------------------------------------------------------------------------

docs/workflows/sync.rst

@@ -1,3 +1,5 @@
+.. _workflows_sync:
+
 Repository Synchronization
 ================================================================================