Various fixes to the pulp_deb docs

* installation docs should reference services
* update "publisher" to "publication"
* remove "publish a repo" as that's not a thing anymore
* update content creation to reflect the current API
* fix various formatting

fixes: #5380
ref: #5376

Signed-off-by: Phil Dibowitz <phil@ipom.com>

CHANGES/5376.doc

@@ -0,0 +1 @@
+Reference the fact you must have both _relative_path and relative_path.

CHANGES/5380.doc

@@ -0,0 +1 @@
+Fix various documentation issues from API changes, plus other misc fixes.

docs/installation.rst

@@ -38,7 +38,7 @@ From Source
 
    sudo -u pulp -i
    source ~/pulpvenv/bin/activate
-   cd pulp_deb
+   cd pulp_deb # assuming you have `git clone`d here.
    pip install -e .
    django-admin runserver 24817
 
@@ -56,8 +56,8 @@ Run Services
 
 .. code-block:: bash
 
-   django-admin runserver 24817
-   gunicorn pulpcore.content:server --bind 'localhost:24816' --worker-class 'aiohttp.GunicornWebWorker' -w 2
+   sudo systemctl restart pulp-content-app
+   sudo systemctl restart pulp-api
    sudo systemctl restart pulp-resource-manager
    sudo systemctl restart pulp-worker@1
    sudo systemctl restart pulp-worker@2

docs/workflows/publish.rst

@@ -4,54 +4,32 @@ Publish and Host
 This section assumes that you have a repository with content in it. To do this, see the
 :doc:`sync` or :doc:`upload` documentation.
 
-Create a Publisher
-------------------
+Create a Publication
+--------------------
 
-Publishers contain extra settings for how to publish. You can use a deb publisher on any
+Publiations contain extra settings for how to publish. You can use a deb publisher on any
 repository that contains deb content::
 
-$ http POST $BASE_ADDR/pulp/api/v3/publishers/deb/default/ name=bar
+    $ http POST $BASE_ADDR/pulp/api/v3/publication/deb/apt/ repository=/pulp/api/v3/repositories/<uuid> simple=true
 
 Response::
 
     {
-        "_href": "http://localhost:24817/pulp/api/v3/repositories/foo/publishers/deb/default/1/",
-        ...
+        "task": "/pulp/api/v3/tasks/<uuid>",
     }
 
 
-Publish a repository with a publisher
--------------------------------------
-
-Use the remote object to kick off a publish task by specifying the repository version to publish.
-Alternatively, you can specify repository, which will publish the latest version.
-
-The result of a publish is a publication, which contains all the information needed for a external package manager
-like ``pip`` or ``apt-get`` to use. Publications are not consumable until they are hosted by a distribution::
-
-$ http POST $BASE_ADDR/pulp/api/v3/publishers/deb/default/1/publish/ repository=$BASE_ADDR/pulp/api/v3/repositories/1/
-
-Response::
-
-    [
-        {
-            "_href": "http://localhost:24817/pulp/api/v3/tasks/fd4cbecd-6c6a-4197-9cbe-4e45b0516309/",
-            "task_id": "fd4cbecd-6c6a-4197-9cbe-4e45b0516309"
-        }
-    ]
-
 Host a Publication (Create a Distribution)
---------------------------------------------
+------------------------------------------
 
 To host a publication, (which makes it consumable by a package manager), users create a distribution which
 will serve the associated publication at ``/pulp/content/<distribution.base_path>``::
 
-$ http POST $BASE_ADDR/pulp/api/v3/distributions/ name='baz' base_path='foo' publication=$BASE_ADDR/publications/1/
+    $ http POST $BASE_ADDR/pulp/api/v3/distributions/deb/apt/ name='baz' base_path='foo' publication=$BASE_ADDR/publications/1/
 
 Response::
 
     {
-        "_href": "http://localhost:24817/pulp/api/v3/distributions/1/",
-       ...
+        "task": "/pulp/api/v3/tasks/<uuid>",
     }
 

docs/workflows/upload.rst

@@ -11,7 +11,7 @@ If you don't already have a repository, create one::
 Response::
 
     {
-        "_href": "http://localhost:24817/pulp/api/v3/repositories/1/",
+        "_href": "/pulp/api/v3/repositories/1/",
         ...
     }
 
@@ -21,28 +21,30 @@ Upload a file to Pulp
 
 Each artifact in Pulp represents a file. They can be created during sync or created manually by uploading a file::
 
-    $ http --form POST $BASE_ADDR/pulp/api/v3/artifacts/ file@./my_content
+    $ http --form POST $BASE_ADDR/pulp/api/v3/artifacts/ file@./foo_1.0-1_amd64.deb
 
 Response::
 
     {
-        "_href": "http://localhost:24817/pulp/api/v3/artifacts/1/",
+        "_href": "/pulp/api/v3/artifacts/1/",
         ...
+        "sha256": "7086dbfcff02666d54af8dd4e9ad5a803027c1326a6fcc1442674ba4780edb5a",
     }
 
 
 Create content from an artifact
 -------------------------------
 
-Now that Pulp has the content, its time to make it into a unit of content.
+Now that Pulp has the content, its time to make it into a unit of content. And yes, until the https://pulp.plan.io/issues/5376 is fixed, you must specify *both* relative_path and _relative_path.
 
-    $ http POST $BASE_ADDR/pulp/api/v3/content/deb/packages/ _artifact=http://localhost:24817/pulp/api/v3/artifacts/1/ filename=my_content
+
+    $ http POST $BASE_ADDR/pulp/api/v3/content/deb/packages/ _artifact=/pulp/api/v3/artifacts/1/ architecture=amd64 package_name=foo description="the best foo" version=1.0-1 sha256=7086dbfcff02666d54af8dd4e9ad5a803027c1326a6fcc1442674ba4780edb5a maintainer="me@sample.com" _relative_path=foo_1.0-1_amd64.deb relative_path=foo_1.0-1_amd64.deb
 
 Response::
 
     {
-        "_href": "http://localhost:24817/pulp/api/v3/content/deb/packages/1/",
-        "artifact": "http://localhost:24817/pulp/api/v3/artifacts/1/",
+        "_href": "/pulp/api/v3/content/deb/packages/1/",
+        "artifact": "/pulp/api/v3/artifacts/1/",
         "digest": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
         "filename": "my-content",
         "_type": "deb.packages"
@@ -51,6 +53,6 @@ Response::
 Add content to a repository
 ---------------------------
 
-Once there is a content unit, it can be added and removed and from to repositories::
+Once there is a content unit, it can be added to and removed from to repositories::
 
-$ http POST $REPO_HREF/pulp/api/v3/repositories/1/versions/ add_content_units:="[\"http://localhost:24817/pulp/api/v3/content/deb/packages/1/\"]"
+    $ http POST $BASE_ADDR/pulp/api/v3/repositories/1/versions/ add_content_units:="[\"http://localhost:24817/pulp/api/v3/content/deb/packages/1/\"]"