Merge pull request pulp#225 from asmacdo/script-docs

Replace commands with scripts

docs/_scripts/add_remove.sh

@@ -0,0 +1,13 @@
+# Manually add content to a repository by creating a new version, creating a task
+export TASK_URL=$(http POST $BASE_ADDR$REPO_HREF'versions/' \
+    add_content_units:="[\"$CONTENT_HREF\"]" \
+    | jq -r '.task')
+
+# Poll the task (here we use a function defined in docs/_scripts/base.sh)
+wait_until_task_finished $BASE_ADDR$TASK_URL
+
+# After the task is complete, it gives us a new repository version
+export REPOVERSION_HREF=$(http $BASE_ADDR$TASK_URL| jq -r '.created_resources | first')
+
+# Lets inspect our newly created RepositoryVersion
+http $BASE_ADDR$REPOVERSION_HREF

docs/_scripts/artifact.sh

@@ -0,0 +1,9 @@
+# Create a dummy file to upload
+echo "Very important content." > test_upload.txt
+
+# Upload the file to Pulp, creating an artifact
+export ARTIFACT_HREF=$(http --form POST $BASE_ADDR/pulp/api/v3/artifacts/ file@./test_upload.txt \
+    | jq -r '._href')
+
+# Lets inspect our newly created artifact
+http $BASE_ADDR$ARTIFACT_HREF

docs/_scripts/base.sh

@@ -0,0 +1,25 @@
+# Set environment variables for default hostname and ports for the API and the Content app
+export BASE_ADDR=http://localhost:24817
+export CONTENT_ADDR=http://localhost:24816
+
+# Necessary for `django-admin`
+export DJANGO_SETTINGS_MODULE=pulpcore.app.settings
+
+# Poll a Pulp task until it is finished.
+wait_until_task_finished() {
+    local task_url=$1
+    while true
+    do
+        local response=$(http $task_url)
+        local state=$(jq -r .state <<< ${response})
+        jq . <<< "${response}"
+        case ${state} in
+            failed|completed|canceled)
+                break
+                ;;
+            *)
+                sleep 1
+                ;;
+        esac
+    done
+}

docs/_scripts/clean.sh

@@ -0,0 +1,10 @@
+# Stop all pulp services
+sudo systemctl stop pulp-content-app pulp-worker@1 pulp-worker@2 pulp-resource-manager pulp-api
+
+# Reset the database (destructive!)
+django-admin reset_db --noinput
+django-admin migrate
+django-admin reset-admin-password --password password
+
+# Restart all pulp services
+sudo systemctl restart pulp-content-app pulp-worker@1 pulp-worker@2 pulp-resource-manager pulp-api

docs/_scripts/content.sh

@@ -0,0 +1,10 @@
+# Create File Content from the artifact
+ http POST $BASE_ADDR/pulp/api/v3/content/file/files/ \
+     relative_path=test_upload.txt \
+    _artifact=$ARTIFACT_HREF
+
+export CONTENT_HREF=$(http :24817/pulp/api/v3/content/file/files/ | \
+    jq -r '.results[] | select(.relative_path == "test_upload.txt") | ._href')
+
+# Lets inspect our newly created file content
+http $BASE_ADDR$CONTENT_HREF

docs/_scripts/destructive_check_sync_publish.sh

@@ -0,0 +1,15 @@
+# This script will execute the component scripts and ensure that the documented examples
+# work as expected.
+
+# From the _scripts directory, run with `source destructive_scripts_check.sh` (source to preserve
+# the environment variables)
+source clean.sh
+source base.sh
+
+source repo.sh
+source remote.sh
+source sync.sh
+
+source publication.sh
+source distribution.sh
+source download_after_sync.sh

docs/_scripts/destructive_check_upload_publish.sh

@@ -0,0 +1,16 @@
+# This script will execute the component scripts and ensure that the documented examples
+# work as expected.
+
+# From the _scripts directory, run with `source destructive_scripts_check.sh` (source to preserve
+# the environment variables)
+source clean.sh
+source base.sh
+
+source repo.sh
+source artifact.sh
+source content.sh
+source add_remove.sh
+
+source publication.sh
+source distribution.sh
+source download_after_upload.sh

docs/_scripts/distribution.sh

@@ -0,0 +1,15 @@
+# Distributions are created asynchronously. Create one, and specify the publication that will
+# be served at the base path specified.
+export TASK_URL=$(http POST $BASE_ADDR/pulp/api/v3/distributions/file/file/ \
+  name='baz' \
+  base_path='foo' \
+  publication=$PUBLICATION_HREF | jq -r '.task')
+
+# Poll the task (here we use a function defined in docs/_scripts/base.sh)
+wait_until_task_finished $BASE_ADDR$TASK_URL
+
+# After the task is complete, it gives us a new file distribution
+export DISTRIBUTION_HREF=$(http $BASE_ADDR$TASK_URL| jq -r '.created_resources | first')
+
+# Lets inspect the Distribution
+http $BASE_ADDR$DISTRIBUTION_HREF

docs/_scripts/download_after_sync.sh

@@ -0,0 +1,5 @@
+# The distribution will return a url that can be used by http clients
+export DISTRIBUTION_BASE_URL=$(http $BASE_ADDR$DISTRIBUTION_HREF | jq -r '.base_url')
+
+# Next we download a file from the distribution
+http -d http://$DISTRIBUTION_BASE_URL/test.iso

docs/_scripts/download_after_upload.sh

@@ -0,0 +1,5 @@
+# The distribution will return a url that can be used by http clients
+export DISTRIBUTION_BASE_URL=$(http $BASE_ADDR$DISTRIBUTION_HREF | jq -r '.base_url')
+
+# Next we download a file from the distribution
+http -d http://$DISTRIBUTION_BASE_URL/test_upload.txt

docs/_scripts/publication.sh

@@ -0,0 +1,13 @@
+# Create a new publication specifying the repository_version.
+# Alternatively, you can specify the repository, and Pulp will assume the latest version.
+export TASK_URL=$(http POST $BASE_ADDR/pulp/api/v3/publications/file/file/ \
+  repository_version=$REPOVERSION_HREF | jq -r '.task')
+
+# Poll the task (here we use a function defined in docs/_scripts/base.sh)
+wait_until_task_finished $BASE_ADDR$TASK_URL
+
+# After the task is complete, it gives us a new file publication
+export PUBLICATION_HREF=$(http $BASE_ADDR$TASK_URL| jq -r '.created_resources | first')
+
+# Lets inspect our newly created Publication.
+http $BASE_ADDR$PUBLICATION_HREF

docs/_scripts/remote.sh

@@ -0,0 +1,10 @@
+# Create a remote that points to an external source of files
+http POST http://localhost:24817/pulp/api/v3/remotes/file/file/ \
+    name='bar' \
+    url='https://repos.fedorapeople.org/pulp/pulp/demo_repos/test_file_repo/PULP_MANIFEST'
+
+# Export an environment variable for the new remote URI.
+export REMOTE_HREF=$(http $BASE_ADDR/pulp/api/v3/remotes/file/file/ | jq -r '.results[] | select(.name == "bar") | ._href')
+
+# Lets inspect our newly created RepositoryVersion.
+http $BASE_ADDR$REMOTE_HREF

docs/_scripts/repo.sh

@@ -0,0 +1,10 @@
+# Start by creating a new repository named "foo":
+http POST $BASE_ADDR/pulp/api/v3/repositories/ name=foo
+
+# If you want to copy/paste your way through the guide,
+# create an environment variable for the repository URI.
+export REPO_HREF=$(http $BASE_ADDR/pulp/api/v3/repositories/ | \
+  jq -r '.results[] | select(.name == "foo") | ._href')
+
+# Lets inspect our newly created repository.
+http $BASE_ADDR$REPO_HREF

docs/_scripts/sync.sh

@@ -0,0 +1,12 @@
+# Using the Remote we just created, we kick off a sync task
+export TASK_URL=$(http POST $BASE_ADDR$REMOTE_HREF'sync/' repository=$REPO_HREF mirror=False \
+  | jq -r '.task')
+
+# Poll the task (here we use a function defined in docs/_scripts/base.sh)
+wait_until_task_finished $BASE_ADDR$TASK_URL
+
+# After the task is complete, it gives us a new repository version
+export REPOVERSION_HREF=$(http $BASE_ADDR$TASK_URL| jq -r '.created_resources | first')
+
+# Lets inspect our newly created RepositoryVersion
+http $BASE_ADDR$REPOVERSION_HREF

docs/workflows/index.rst

@@ -19,17 +19,12 @@ in the home directory. The ``.netrc`` should have the following configuration:
 
     machine localhost
     login admin
-    password admin
+    password password
 
 If you configured the ``admin`` user with a different password, adjust the configuration
 accordingly. If you prefer to specify the username and password with each request, please see
 ``httpie`` documentation on how to do that.
 
-To make these workflows copy/pastable, we make use of environment variables. The first variable to
-set is the hostname and port::
-
-   $ export BASE_ADDR=http://<hostname>:24817
-
 **jq**
 
 This documentation makes use of the `jq library <https://stedolan.github.io/jq/>`_
@@ -42,6 +37,7 @@ library with:
 .. toctree::
    :maxdepth: 2
 
+   scripting
    sync
    upload
    publish-host

docs/workflows/publish-host.rst

@@ -7,26 +7,52 @@ this, see the :doc:`sync` or :doc:`upload` documentation.
 Create a Publication
 --------------------
 
-``$ http POST http://localhost:24817/pulp/api/v3/publications/file/file/ repository=$REPO_HREF``
+.. literalinclude:: ../_scripts/publication.sh
+   :language: bash
 
-.. code:: json
+Publication GET Response (after task is complete)::
 
     {
-        "task": "/pulp/api/v3/tasks/fd4cbecd-6c6a-4197-9cbe-4e45b0516309/"
+        "_created": "2019-05-16T19:28:42.971611Z",
+        "_href": "/pulp/api/v3/publications/file/file/7d5440f6-202c-4e71-ace2-14c534f6df9e/",
+        "_type": "file.file",
+        "distributions": [],
+        "publisher": null,
+        "repository": "http://localhost:24817/pulp/api/v3/repositories/%3CRepository:%20foo%3E/",
+        "repository_version": "/pulp/api/v3/repositories/e242c556-bf46-4330-9c81-0be5432e55ba/versions/1/"
     }
 
-``$ export PUBLICATION_HREF=$(http :24817/pulp/api/v3/publications/file/file/ | jq -r '.results[0] | ._href')``
-
 Reference: `File Publication Usage <../restapi.html#tag/publications>`_
 
 Create a Distribution for the Publication
 -----------------------------------------
 
-``$ http POST http://localhost:24817/pulp/api/v3/distributions/file/file/ name='baz' base_path='foo' publication=$PUBLICATION_HREF``
+.. literalinclude:: ../_scripts/publication.sh
+   :language: bash
+
+Distribution GET Response (after task is complete)::
+
+    {
+        "_created": "2019-05-16T19:28:45.135868Z",
+        "_href": "/pulp/api/v3/distributions/file/file/9e9e07cb-b30f-41c5-a98b-583185f907e2/",
+        "base_path": "foo",
+        "base_url": "localhost:24816/pulp/content/foo",
+        "content_guard": null,
+        "name": "baz",
+        "publication": "/pulp/api/v3/publications/file/file/7d5440f6-202c-4e71-ace2-14c534f6df9e/"
+    }
 
 Reference: `File Distribution Usage <../restapi.html#tag/distributions>`_
 
-Download ``foo.tar.gz`` from Pulp
+Download ``test.iso`` from Pulp
 ---------------------------------
 
-``$ http GET http://localhost:24816/pulp/content/foo/foo.tar.gz``
+If you created your repository version using the :doc:`sync` workflow:
+
+.. literalinclude:: ../_scripts/download_after_sync.sh
+   :language: bash
+
+If you created your repository version using the :doc:`upload` workflow:
+
+.. literalinclude:: ../_scripts/download_after_upload.sh
+   :language: bash

docs/workflows/scripting.rst

@@ -0,0 +1,32 @@
+Scripting
+=========
+
+Each workflow renders bash scripts that allow the developers to ensure the continued correctness of
+the instructions. These scripts may also be helpful to users as a basis for their own scripts. All
+of the scripts can be found at https://github.com/pulp/pulp_file/tree/master/docs/_scripts/
+
+The following scripts are used in conjunction with all the workflow scripts:
+
+**Base**
+
+.. literalinclude:: ../_scripts/base.sh
+   :language: bash
+
+**Cleanup (Destructive)**
+
+.. literalinclude:: ../_scripts/clean.sh
+   :language: bash
+
+Correctness Check (Destructive)
+-------------------------------
+
+To check the correctness of the sync and publish workflow scripts, they can all be run together using:
+
+.. literalinclude:: ../_scripts/destructive_check_sync_publish.sh
+   :language: bash
+
+To check the correctness of the upload and publish workflow scripts, they can all be run together using:
+script.
+
+.. literalinclude:: ../_scripts/destructive_check_upload_publish.sh
+   :language: bash