Update user docs

Author: jobselko

docs/user/guides/_SUMMARY.md

@@ -1,4 +1,4 @@
-* [Setup your own PyPI](pypi.md)
+* [Set up your own PyPI](pypi.md)
 * [Sync from Remote Repositories](sync.md)
 * [Upload and Manage Content](upload.md)
 * [Publish and Host Python Content](publish.md)

docs/user/guides/publish.md

@@ -24,18 +24,20 @@ Distribution before it is consumable).
 
     ```
     {
-      "pulp_href": "/pulp/api/v3/publications/python/pypi/cad6007d-7172-41d1-8c22-0ec95e1d242a/",
-      "pulp_created": "2021-03-09T04:30:16.686784Z",
-      "repository_version": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/versions/1/",
-      "repository": "/pulp/api/v3/repositories/python/python/8fbb24ee-dc91-44f4-a6ee-beec60aa542d/",
+      "pulp_href": "/pulp/api/v3/publications/python/pypi/0196ba31-cd04-7aba-a7b4-71a98a976745/",
+      "prn": "prn:python.pythonpublication:0196ba31-cd04-7aba-a7b4-71a98a976745",
+      "pulp_created": "2025-05-10T12:35:48.103758Z",
+      "pulp_last_updated": "2025-05-10T12:35:48.205361Z",
+      "repository_version": "/pulp/api/v3/repositories/python/python/0196ba30-e15e-71ea-9867-33aeceb5a87e/versions/1/",
+      "repository": "/pulp/api/v3/repositories/python/python/0196ba30-e15e-71ea-9867-33aeceb5a87e/",
       "distributions": []
     }
     ```
 
 ## Host a Publication (Create a Distribution)
 
 To host a publication, (which makes it consumable by `pip`), users create a distribution which
-will serve the associated publication at `/pypi/<distribution.base_path>/`
+will serve the associated publication at `$BASE_ADDR/pypi/$DIST_BASE_PATH/`.
 
 === "Run"
 
@@ -49,15 +51,22 @@ will serve the associated publication at `/pypi/<distribution.base_path>/`
 
     ```
     {
-       "pulp_href": "/pulp/api/v3/distributions/python/pypi/4839c056-6f2b-46b9-ac5f-88eb8a7739a5/",
-       "pulp_created": "2021-03-09T04:36:48.289737Z",
-       "base_path": "foo",
-       "base_url": "/pypi/foo/",
-       "content_guard": null,
-       "pulp_labels": {},
-       "name": "foo",
-       "publication": "/pulp/api/v3/publications/python/pypi/a09111b1-6bce-43ac-aed7-2e8441c22704/"
-     }
+      "pulp_href": "/pulp/api/v3/distributions/python/pypi/0196ba32-0be6-7f85-bbb3-cf561a4e2d88/",
+      "prn": "prn:python.pythondistribution:0196ba32-0be6-7f85-bbb3-cf561a4e2d88",
+      "pulp_created": "2025-05-10T12:36:04.200189Z",
+      "pulp_last_updated": "2025-05-10T12:36:04.200232Z",
+      "base_path": "foo",
+      "base_url": "http://localhost:5001/pypi/foo/",
+      "content_guard": null,
+      "no_content_change_since": "2025-05-10T12:36:04.200232Z",
+      "hidden": false,
+      "pulp_labels": {},
+      "name": "foo",
+      "repository": null,
+      "publication": "/pulp/api/v3/publications/python/pypi/0196ba31-cd04-7aba-a7b4-71a98a976745/",
+      "allow_uploads": true,
+      "remote": null
+    }
     ```
 
 ## Automate Publication and Distribution
@@ -68,7 +77,7 @@ updated automatically when new repository versions are created.
 ```bash
 # This configures the repository to produce new publications when a new version is created
 pulp python repository update --name foo --autopublish
-# This configures the distribution to be track the latest repository version for a given repository
+# This configures the distribution to track the latest repository version for a given repository
 pulp python distribution update --name foo --repository foo
 ```
 
@@ -77,7 +86,7 @@ pulp python distribution update --name foo --repository foo
     Functionality may not work or may be incomplete. Also, backwards compatibility when upgrading
     is not guaranteed.
 
-## Enable Pull-Through Caching:
+## Enable Pull-Through Caching
 
 Only packages present in your repository will be available from your index, but adding a remote source to
 your distribution will enable the pull-through cache feature. This feature allows you to install any package
@@ -101,28 +110,26 @@ pulp python distribution update --name foo --remote bar
 The metadata and packages can now be retrieved from the distribution:
 
 ```bash
-$ http $BASE_ADDR/pypi/foo/simple/
-$ http $BASE_ADDR/pypi/foo/simple/shelf-reader/
+http "${BASE_ADDR}/pypi/foo/simple/"
+http "${BASE_ADDR}/pypi/foo/simple/shelf-reader/"
 ```
 
 !!! note
     When domains are enabled, it is necessary to include the domain name within the URL, like so:
-    `$BASE_ADDR/pypi/${DOMAIN_NAME}/foo/simple/`
+    `$BASE_ADDR/pypi/$DOMAIN_NAME/foo/simple/`
 
 The content is also pip installable:
 
 ```bash
-$ pip install --trusted-host localhost -i $BASE_ADDR/pypi/foo/simple/ shelf-reader
+pip install --trusted-host localhost -i "${BASE_ADDR}/pypi/foo/simple/" shelf-reader
 ```
 
-If you don't want to specify the distribution path every time, you can modify your `pip.conf`
-file. See the [pip docs](https://pip.pypa.io/en/stable/user_guide/#configuration) for more
-detail.:
+If you don't want to specify the distribution path every time, you can modify your `pip.conf` file:
 
 === "Run"
 
     ```bash
-    $ cat pip.conf
+    cat pip.conf
     ```
 
 === "Output"
@@ -135,5 +142,7 @@ detail.:
 The above configuration informs `pip` to install from `pulp`:
 
 ```bash
-$ pip install --trusted-host localhost shelf-reader
+pip install --trusted-host localhost shelf-reader
 ```
+
+See the [pip docs](https://pip.pypa.io/en/stable/topics/configuration) for more details.

docs/user/guides/pypi.md

@@ -1,9 +1,9 @@
-# Setup your own PyPI:
+# Set up your own PyPI
 
-This section guides you through the quickest way to setup `pulp_python` to act as your very own
+This section guides you through the quickest way to set up `pulp_python` to act as your very own
 private `PyPI`.
 
-## Create a Repository:
+## Create a Repository
 
 Repositories are the base objects `Pulp` uses to store and organize its content. They are automatically
 versioned when content is added or deleted and allow for easy rollbacks to previous versions.
@@ -19,20 +19,22 @@ versioned when content is added or deleted and allow for easy rollbacks to previ
 
     ```
     {
-         "pulp_href": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/",
-         "pulp_created": "2021-06-02T14:54:53.387054Z",
-         "versions_href": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/versions/",
-         "pulp_labels": {},
-         "latest_version_href": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/versions/1/",
-         "name": "foo",
-         "description": null,
-         "retained_versions": null,
-         "remote": null,
-         "autopublish": false
-     }
+      "pulp_href": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/",
+      "prn": "prn:python.pythonrepository:0196ba29-52b9-7cf4-b12e-f3247f0eb3dc",
+      "pulp_created": "2025-05-10T12:26:32.506906Z",
+      "pulp_last_updated": "2025-05-10T12:26:32.517333Z",
+      "versions_href": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/versions/",
+      "pulp_labels": {},
+      "latest_version_href": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/versions/0/",
+      "name": "foo",
+      "description": null,
+      "retain_repo_versions": null,
+      "remote": null,
+      "autopublish": false
+    }
     ```
 
-## Create a Distribution:
+## Create a Distribution
 
 Distributions serve the content stored in repositories so that it can be used by tools like `pip`.
 
@@ -46,35 +48,44 @@ Distributions serve the content stored in repositories so that it can be used by
 
     ```
     {
-      "pulp_href": "/pulp/api/v3/distributions/python/pypi/e8438593-fd40-4654-8577-65398833c331/",
-      "pulp_created": "2021-06-03T20:04:18.233230Z",
+      "pulp_href": "/pulp/api/v3/distributions/python/pypi/0196ba29-8f95-776b-a782-78d7838f3f9f/",
+      "prn": "prn:python.pythondistribution:0196ba29-8f95-776b-a782-78d7838f3f9f",
+      "pulp_created": "2025-05-10T12:26:48.086775Z",
+      "pulp_last_updated": "2025-05-10T12:26:48.086806Z",
       "base_path": "my-pypi",
-      "base_url": "https://pulp3-source-fedora33.localhost.example.com/pypi/foo/",
+      "base_url": "http://localhost:5001/pypi/my-pypi/",
       "content_guard": null,
+      "no_content_change_since": null,
+      "hidden": false,
       "pulp_labels": {},
       "name": "my-pypi",
-      "repository": "/pulp/api/v3/repositories/python/python/3fe0d204-217f-4250-8177-c83b30751fca/",
+      "repository": "/pulp/api/v3/repositories/python/python/0196ba29-52b9-7cf4-b12e-f3247f0eb3dc/",
       "publication": null,
-      "allow_uploads": true
+      "allow_uploads": true,
+      "remote": null
     }
     ```
 
-## Upload and Install Packages:
+## Upload and Install Packages
 
 Packages can now be uploaded to the index using your favorite Python tool. The index url will be available
-at `/pypi/<distribution.base_path>/simple/`.
+at `$BASE_ADDR/pypi/$DIST_BASE_PATH/simple/`.
 
 ```bash
+BASE_ADDR="http://localhost:5001"
+# Prepare package
+git clone https://github.com/asmacdo/shelf-reader.git
+PLUGIN_SOURCE="shelf-reader"
 # Build custom package
-python -m build $PLUGIN_SOURCE
+python -m build "$PLUGIN_SOURCE"
 # Upload built package distributions to my-pypi
-twine upload --repository-url $BASE_ADDR/pypi/my-pypi/simple/ -u admin -p password "$PLUGIN_SOURCE"dist/*
+twine upload --repository-url "${BASE_ADDR}/pypi/my-pypi/simple/" -u admin -p password "${PLUGIN_SOURCE}/dist/"*
 ```
 
 Packages can then be installed using your favorite Python tool:
 
 ```bash
-pip install --trusted-host localhost -i $BASE_ADDR/pypi/my-pypi/simple/ shelf-reader
+pip install --trusted-host localhost -i "${BASE_ADDR}/pypi/my-pypi/simple/" shelf-reader
 ```
 
 Now you have a fully operational Python package index. Check out the other workflows to see more features of