docs: make docs spread-testable (#143)

docs/howto/code/craft-cli-upload-progress/craft_cli_upload.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+from pathlib import Path
+import sys
+
+from craft_cli import emit, EmitterMode
+from craft_store import StoreClient, endpoints
+from requests_toolbelt import MultipartEncoder, MultipartEncoderMonitor
+
+
+emit.init(EmitterMode.BRIEF, "craft.store-howto", "Starting howto app.")
+
+store_client = StoreClient(
+    base_url="https://dashboard.staging.snapcraft.io",
+    storage_base_url="https://upload.apps.staging.ubuntu.com",
+    endpoints=endpoints.SNAP_STORE,
+    user_agent="Craft Store Howto Agent",
+    application_name="craft-store-upload",
+    environment_auth="SNAPCRAFT_STORE_CREDENTIALS",
+)
+
+
+def create_callback(encoder: MultipartEncoder):
+    with emit.progress_bar("Uploading...", encoder.len, delta=False) as progress:
+
+        def progress_callback(monitor: MultipartEncoderMonitor):
+            progress.advance(monitor.bytes_read)
+
+    return progress_callback
+
+
+upload_id = store_client.upload_file(
+    monitor_callback=create_callback,
+    filepath=Path(sys.argv[1]),
+)
+
+emit.message(f"upload-id: {upload_id}")
+emit.ended_ok()

docs/howto/code/craft-cli-upload-progress/task.yaml

@@ -0,0 +1,21 @@
+###########################################
+# IMPORTANT
+# Comments matter!
+# The docs use the wrapping comments as
+# markers for including said instructions
+# as snippets in the docs.
+###########################################
+summary: test for the craft-cli upload howto.
+
+prepare: |
+  python3 -m venv venv
+  source venv/bin/activate
+  pip install craft-cli $PROJECT_PATH
+
+execute: |
+  source venv/bin/activate
+  snap download hello-world
+  mv *.snap test.snap
+  # [docs:run]
+  python3 craft_cli_upload.py test.snap
+  # [docs:run-end]

docs/howto/craft-cli-upload-progress.rst

@@ -6,44 +6,12 @@ Using craft-cli for upload progress
 Progress can be provided by use of craft-cli_. This example will upload
 ``./test.snap`` with something that looks like the following:
 
-.. code-block:: python
+The example requires setting the environment variable
+``SNAPCRAFT_STORE_CREDENTIALS`` using a file generated by
+`snapcraft export-login`_.
 
-  #!/usr/bin/env python
-  from pathlib import Path
+.. literalinclude:: code/craft-cli-upload-progress/craft_cli_upload.py
+    :language: python
 
-  from craft_cli import emit, EmitterMode
-  from craft_store import StoreClient, endpoints
-  from requests_toolbelt import MultipartEncoder, MultipartEncoderMonitor
-
-
-  emit.init(EmitterMode.NORMAL, "craft.store-howto", "Starting howto app.")
-
-  store_client = StoreClient(
-      base_url="https://dashboard.staging.snapcraft.io",
-      storage_base_url="https://upload.apps.staging.ubuntu.com",
-      endpoints=endpoints.SNAP_STORE,
-      user_agent="Craft Store Howto Agent",
-      application_name="craft-store-upload",
-  )
-
-
-  def create_callback(encoder: MultipartEncoder):
-      with emit.progress_bar("Uploading...", encoder.len, delta=False) as progress:
-
-          def progress_callback(monitor: MultipartEncoderMonitor):
-              progress.advance(monitor.bytes_read)
-
-      return progress_callback
-
-
-  upload_id = store_client.upload_file(
-      monitor_callback=create_callback,
-      filepath=Path("test.snap"),
-  )
-
-  emit.message(f"upload-id: {upload_id}", intermediate=True)
-  emit.ended_ok()
-
-
-
-.. _craft-cli: https://craft-cli.readthedocs.org/
+.. _craft-cli: https://canonical-craft-cli.readthedocs-hosted.com/en/latest/
+.. _snapcraft export-login: https://snapcraft.io/docs/snapcraft-authentication

docs/tutorials/snap-store-login-ubuntu-one.rst

@@ -6,7 +6,7 @@ Login to the Snap Store using Ubuntu One
 At the end of this tutorial you will have successfully written a
 script that can log you into the Snap Store using Ubuntu One
 (https://login.ubuntu.com) and have those credentials stored for the
-combination of Dashboard endpoint (https://dashboard.snapcraft.io) and
+combination of the `Snapcraft Dashboard`_ and
 application name (``ubuntu1-dashboard``).
 
 Prerequisites
@@ -91,3 +91,5 @@ Run
 Run the saved python module to login::
 
   $ python snap_store_login_ubuntu_one.py
+
+.. _Snapcraft Dashboard: https://dashboard.snapcraft.io/stores/snaps/

pyproject.toml

@@ -200,7 +200,7 @@ exclude = [
     "build",
     "tests",
     "results",
-    "docs/sphinx-docs-starter-pack",
+    "docs",
 ]
 warn_unused_configs = true
 warn_redundant_casts = true

spread.yaml

@@ -0,0 +1,67 @@
+project: craft-store
+
+path: /craft-store
+environment:
+  PROJECT_PATH: /craft-store
+  PATH: /snap/bin:$PATH:$PROJECT_PATH/tools/spread
+  CRAFT_STORE_CHARMCRAFT_CREDENTIALS: '$(HOST: echo $CRAFT_STORE_CHARMCRAFT_CREDENTIALS)'
+  SNAPCRAFT_STORE_CREDENTIALS: '$(HOST: echo $SNAPCRAFT_STORE_CREDENTIALS)'
+
+backends:
+  google:
+    key: '$(HOST: echo "$SPREAD_GOOGLE_KEY")'
+    location: snapd-spread/us-east1-b
+    halt-timeout: 2h
+    systems:
+      - ubuntu-22.04-64:
+          workers: 2
+          storage: 40G
+  multipass:
+    type: adhoc
+    allocate: |
+      sleep 0.$RANDOM  # Minimize chances of a race condition
+      if [[ ! -f $HOME/.spread/multipass-count ]]; then
+        mkdir -p $HOME/.spread
+        echo 0 > $HOME/.spread/multipass-count
+      fi
+      instance_num=$(< $HOME/.spread/multipass-count)
+      echo $(( $instance_num + 1 )) > $HOME/.spread/multipass-count
+      multipass_image=$(echo ${SPREAD_SYSTEM} | sed -e s/ubuntu-// -e s/-64//)
+
+      system=$(echo "${SPREAD_SYSTEM}" | tr . -)
+      instance_name="spread-${SPREAD_BACKEND}-${instance_num}-${system}"
+
+      multipass launch --cpus 2 --disk 20G --memory 2G --name "${instance_name}" "${multipass_image}"
+
+      # Enable PasswordAuthentication for root over SSH.
+      multipass exec "$instance_name" -- \
+        sudo sh -c "echo root:${SPREAD_PASSWORD} | sudo chpasswd"
+      multipass exec "$instance_name" -- \
+        sudo sh -c \
+        "sed -i /etc/ssh/sshd_config -e 's/^PasswordAuthentication.*/PasswordAuthentication yes/' -e 's/^#PermitRootLogin.*/PermitRootLogin yes/'"
+      multipass exec "$instance_name" -- \
+        sudo systemctl restart ssh
+
+      # Get the IP from the instance
+      ip=$(multipass info --format csv "$instance_name" | tail -1 | cut -d\, -f3)
+      ADDRESS "$ip"
+    discard: |
+      instance_name=$(multipass list --format csv | grep $SPREAD_SYSTEM_ADDRESS | cut -f1 -d\,)
+      multipass delete --purge "${instance_name}"
+    systems:
+      - ubuntu-22.04-64:
+          workers: 2
+
+prepare: |
+  apt-get update
+  apt-get --yes install python3.10-venv
+
+suites:
+#  docs/tutorials/code/:
+#    summary: tests basic tutorials from the docs
+
+  docs/howto/code/:
+    summary: tests how-to guides from the docs
+
+#  docs/reference/code/:
+#    summary: tests reference code from the docs