Remove placeholders and numbered files and fix images

* Add unchanged 'Start Here' from pulpproject.org * Update 'Start Here' page * Remove 'docs/sections', which is now provided by pulp-docs * Remove the 'triage-needed' tmp dirs. We'll handle this later * Fix images on admin/learn/rbac and user/learn/concepts * Move settings and tech-preview to Reference * Revert asset dir rename and rename learn/index * Use new _SUMMARY.md file for ordering and clean numbered filenames * Fix some wording * Fix some wrong rst conversion link Co-authored-by: Ľuboš Mjachky <[email protected]> [noissue]
pulp · Jun 24, 2024 · bd374a3 · bd374a3
1 parent 530a9fb
commit bd374a3
Show file tree

Hide file tree

Showing 75 changed files with 92 additions and 221 deletions.
diff --git a/docs/diagrams_src/concept-add-repo.dot b/docs/diagrams_src/concept-add-repo.dot
@@ -18,4 +18,4 @@ rectangle "Add content to repository" {
   (RV1) -right-> N
   N -right-> (RV2)
 }
-@enduml
+@enduml
diff --git a/staging_docs/admin/guides/_SUMMARY.md b/staging_docs/admin/guides/_SUMMARY.md
@@ -0,0 +1,7 @@
+* Authentication
+    * [Using Basic Auth](auth/basic.md)
+    * [Using external service](auth/external.md)
+    * [Using Keycloak](auth/keycloak.md)
+    * [Using JSON Header](auth/json_header.md)
+* *.md
+
diff --git a/...s/admin/guides/authentication/02-basic.md → staging_docs/admin/guides/auth/basic.md b/...s/admin/guides/authentication/02-basic.md → staging_docs/admin/guides/auth/basic.md
diff --git a/...min/guides/authentication/03-webserver.md → staging_docs/admin/guides/auth/external.md b/...min/guides/authentication/03-webserver.md → staging_docs/admin/guides/auth/external.md
diff --git a/...dmin/guides/authentication/01-overview.md → staging_docs/admin/guides/auth/index.md b/...dmin/guides/authentication/01-overview.md → staging_docs/admin/guides/auth/index.md
diff --git a/...n/guides/authentication/05-json_header.md → ...ing_docs/admin/guides/auth/json_header.md b/...n/guides/authentication/05-json_header.md → ...ing_docs/admin/guides/auth/json_header.md
diff --git a/...dmin/guides/authentication/04-keycloak.md → staging_docs/admin/guides/auth/keycloak.md b/...dmin/guides/authentication/04-keycloak.md → staging_docs/admin/guides/auth/keycloak.md
diff --git a/staging_docs/admin/learn/architecture.md b/staging_docs/admin/learn/architecture.md
@@ -4,9 +4,10 @@ Pulp's architecture has three components to it: a REST API, a content serving ap
 tasking system. Each component can be horizontally scaled for both high availability and/or
 additional capacity for that part of the architecture.
 
-```
-/static/architecture.png
-```
+<figure markdown="span">
+  ![Pulp Architecture](site:pulpcore/docs/assets/images/architecture.png)
+  <!-- <figcaption>Image caption</figcaption> -->
+</figure>
 
 ## REST API
 

diff --git a/staging_docs/admin/learn/settings.md → staging_docs/admin/reference/settings.md b/staging_docs/admin/learn/settings.md → staging_docs/admin/reference/settings.md
diff --git a/staging_docs/admin/learn/tech-preview.md → staging_docs/admin/reference/tech-preview.md b/staging_docs/admin/learn/tech-preview.md → staging_docs/admin/reference/tech-preview.md
diff --git a/staging_docs/assets/static/.gitkeep → staging_docs/assets/images/.gitkeep b/staging_docs/assets/static/.gitkeep → staging_docs/assets/images/.gitkeep
diff --git a/staging_docs/assets/static/architecture.png → staging_docs/assets/images/architecture.png b/staging_docs/assets/static/architecture.png → staging_docs/assets/images/architecture.png
diff --git a/staging_docs/assets/images/concept-add-repo.png b/staging_docs/assets/images/concept-add-repo.png
diff --git a/staging_docs/assets/images/concept-content.png b/staging_docs/assets/images/concept-content.png
diff --git a/staging_docs/assets/images/concept-publish.png b/staging_docs/assets/images/concept-publish.png
diff --git a/staging_docs/assets/images/concept-remote.png b/staging_docs/assets/images/concept-remote.png
diff --git a/staging_docs/assets/images/concept-repository.png b/staging_docs/assets/images/concept-repository.png
diff --git a/...ets/static/deferred_download_sequence.png → ...ets/images/deferred_download_sequence.png b/...ets/static/deferred_download_sequence.png → ...ets/images/deferred_download_sequence.png
diff --git a/...ing_docs/assets/static/lazy_component.png → ...ing_docs/assets/images/lazy_component.png b/...ing_docs/assets/static/lazy_component.png → ...ing_docs/assets/images/lazy_component.png
diff --git a/staging_docs/assets/static/node-anatomy.png → staging_docs/assets/images/node-anatomy.png b/staging_docs/assets/static/node-anatomy.png → staging_docs/assets/images/node-anatomy.png
diff --git a/staging_docs/assets/static/node-topology.png → staging_docs/assets/images/node-topology.png b/staging_docs/assets/static/node-topology.png → staging_docs/assets/images/node-topology.png
diff --git a/staging_docs/assets/static/pulp-exp1.png → staging_docs/assets/images/pulp-exp1.png b/staging_docs/assets/static/pulp-exp1.png → staging_docs/assets/images/pulp-exp1.png
diff --git a/..._docs/assets/static/rbac_architecture.png → ..._docs/assets/images/rbac_architecture.png b/..._docs/assets/static/rbac_architecture.png → ..._docs/assets/images/rbac_architecture.png
diff --git a/...ing_docs/dev/guides/triage-needed!/git.md → staging_docs/dev/guides/git.md b/...ing_docs/dev/guides/triage-needed!/git.md → staging_docs/dev/guides/git.md
diff --git a/...ides/triage-needed!/plugin-walkthrough.md → ...ing_docs/dev/guides/plugin-walkthrough.md b/...ides/triage-needed!/plugin-walkthrough.md → ...ing_docs/dev/guides/plugin-walkthrough.md
diff --git a/...riage-needed!/pull-request-walkthrough.md → ...cs/dev/guides/pull-request-walkthrough.md b/...riage-needed!/pull-request-walkthrough.md → ...cs/dev/guides/pull-request-walkthrough.md
diff --git a/.../guides/triage-needed!/release_process.md → staging_docs/dev/guides/release_process.md b/.../guides/triage-needed!/release_process.md → staging_docs/dev/guides/release_process.md
diff --git a/...concepts/domains/domains_compatibility.md → ...ev/learn/domains/domains_compatibility.md b/...concepts/domains/domains_compatibility.md → ...ev/learn/domains/domains_compatibility.md
diff --git a/...iage-needed!/topics/content-protection.md → ...ocs/dev/learn/other/content-protection.md b/...iage-needed!/topics/content-protection.md → ...ocs/dev/learn/other/content-protection.md
diff --git a/...rn/triage-needed!/topics/documentation.md → ...ing_docs/dev/learn/other/documentation.md b/...rn/triage-needed!/topics/documentation.md → ...ing_docs/dev/learn/other/documentation.md
diff --git a/...n/triage-needed!/topics/error-handling.md → ...ng_docs/dev/learn/other/error-handling.md b/...n/triage-needed!/topics/error-handling.md → ...ng_docs/dev/learn/other/error-handling.md
diff --git a/...triage-needed!/topics/how-plugins-work.md → ..._docs/dev/learn/other/how-plugins-work.md b/...triage-needed!/topics/how-plugins-work.md → ..._docs/dev/learn/other/how-plugins-work.md
diff --git a/...n/triage-needed!/topics/how-to-doc-api.md → ...ng_docs/dev/learn/other/how-to-doc-api.md b/...n/triage-needed!/topics/how-to-doc-api.md → ...ng_docs/dev/learn/other/how-to-doc-api.md
diff --git a/...triage-needed!/topics/metadata-signing.md → ..._docs/dev/learn/other/metadata-signing.md b/...triage-needed!/topics/metadata-signing.md → ..._docs/dev/learn/other/metadata-signing.md
diff --git a/...ge-needed!/topics/object-relationships.md → ...s/dev/learn/other/object-relationships.md b/...ge-needed!/topics/object-relationships.md → ...s/dev/learn/other/object-relationships.md
diff --git a/...riage-needed!/topics/on-demand-support.md → ...docs/dev/learn/other/on-demand-support.md b/...riage-needed!/topics/on-demand-support.md → ...docs/dev/learn/other/on-demand-support.md
diff --git a/...n/triage-needed!/topics/planning-guide.md → ...ng_docs/dev/learn/other/planning-guide.md b/...n/triage-needed!/topics/planning-guide.md → ...ng_docs/dev/learn/other/planning-guide.md
diff --git a/.../learn/triage-needed!/topics/releasing.md → staging_docs/dev/learn/other/releasing.md b/.../learn/triage-needed!/topics/releasing.md → staging_docs/dev/learn/other/releasing.md
diff --git a/.../triage-needed!/topics/task-scheduling.md → ...g_docs/dev/learn/other/task-scheduling.md b/.../triage-needed!/topics/task-scheduling.md → ...g_docs/dev/learn/other/task-scheduling.md
diff --git a/...ev/learn/triage-needed!/concepts/index.md → staging_docs/dev/learn/plugin-concepts.md b/...ev/learn/triage-needed!/concepts/index.md → staging_docs/dev/learn/plugin-concepts.md
diff --git a/...ge-needed!/concepts/rbac/access_policy.md → staging_docs/dev/learn/rbac/access_policy.md b/...ge-needed!/concepts/rbac/access_policy.md → staging_docs/dev/learn/rbac/access_policy.md
@@ -68,7 +68,7 @@ These names correspond with the [default DRF viewset action names](https://www.d
 ## Authorization Conditions
 
 Each policy statement can contain [drf-access-policy conditions](https://rsinger86.github.io/drf-access-policy/statement_elements/#condition) which is useful for verifying a user has one or
-more permissions. Pulp ships many built-in checks. See the `permission_checking_machinery`
+more permissions. Pulp ships many built-in checks. See the [permission_checking_machinery](site:pulpcore/docs/dev/learn/rbac/permissions/)
 documentation for more information on available checks.
 
 When multiple conditions are present, **all** of them must return True for the request to be

diff --git a/...epts/rbac/adding_automatic_permissions.md → ...earn/rbac/adding_automatic_permissions.md b/...epts/rbac/adding_automatic_permissions.md → ...earn/rbac/adding_automatic_permissions.md
diff --git a/.../triage-needed!/concepts/rbac/overview.md → staging_docs/dev/learn/rbac/index.md b/.../triage-needed!/concepts/rbac/overview.md → staging_docs/dev/learn/rbac/index.md
@@ -11,28 +11,23 @@ The goals of the authorization system are to:
 
 Pulp's authorization model has the following architecture:
 
-```{image} /static/rbac_architecture.png
-:align: center
-```
+![RBAC Architecture](site:pulpcore/docs/assets/images/rbac_architecture.png)
 
-```{eval-rst}
+Task Permissions Check:
+:  A permission check that occurs inside of Task code. This tends to use
+   permission checking calls like `has_perm` or `has_perms`
+   [provided by Django](https://docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.has_perm).
 
-:Task Permissions Check: A permission check that occurs inside of Task code. This tends to use
-    permission checking calls like `has_perm` or `has_perms` `provided by Django <https://
-    docs.djangoproject.com/en/4.2/ref/contrib/auth/#django.contrib.auth.models.User.has_perm>`_.
+Permission Checking Machinery
+: A set of methods which can check various conditions such as if a
+  requesting user has a given permission, or is a member of a group that has a given permission,
+  etc. See the [permission_checking_machinery](site:pulpcore/docs/dev/learn/rbac/permissions/) section for the complete list of available
+  methods.
 
-:Permission Checking Machinery: A set of methods which can check various conditions such as if a
-    requesting user has a given permission, or is a member of a group that has a given permission,
-    etc. See the :ref:`permission_checking_machinery` section for the complete list of available
-    methods.
+Users and Groups
+: Users and Groups live in the Django database and are used by the Permission Checking Machinery.
+  See the [users_and_groups](site:pulpcore/docs/dev/learn/rbac/users_groups/) documentation for more information.
 
-:Users and Groups: Users and Groups live in the Django database and are used by the Permission
-    Checking Machinery. See the :ref:`users_and_groups` documentation for more information.
-
-
-Getting Started
----------------
-```
 
 ## Getting Started
 

diff --git a/...iage-needed!/concepts/rbac/permissions.md → staging_docs/dev/learn/rbac/permissions.md b/...iage-needed!/concepts/rbac/permissions.md → staging_docs/dev/learn/rbac/permissions.md
diff --git a/...needed!/concepts/rbac/queryset_scoping.md → ...g_docs/dev/learn/rbac/queryset_scoping.md b/...needed!/concepts/rbac/queryset_scoping.md → ...g_docs/dev/learn/rbac/queryset_scoping.md
diff --git a/...age-needed!/concepts/rbac/users_groups.md → staging_docs/dev/learn/rbac/users_groups.md b/...age-needed!/concepts/rbac/users_groups.md → staging_docs/dev/learn/rbac/users_groups.md
diff --git a/...ed!/concepts/subclassing/import-export.md → ...cs/dev/learn/subclassing/import-export.md b/...ed!/concepts/subclassing/import-export.md → ...cs/dev/learn/subclassing/import-export.md
diff --git a/...ge-needed!/concepts/subclassing/models.md → staging_docs/dev/learn/subclassing/models.md b/...ge-needed!/concepts/subclassing/models.md → staging_docs/dev/learn/subclassing/models.md
diff --git a/...ded!/concepts/subclassing/pull-through.md → ...ocs/dev/learn/subclassing/pull-through.md b/...ded!/concepts/subclassing/pull-through.md → ...ocs/dev/learn/subclassing/pull-through.md
diff --git a/...eded!/concepts/subclassing/replication.md → ...docs/dev/learn/subclassing/replication.md b/...eded!/concepts/subclassing/replication.md → ...docs/dev/learn/subclassing/replication.md
diff --git a/...eded!/concepts/subclassing/serializers.md → ...docs/dev/learn/subclassing/serializers.md b/...eded!/concepts/subclassing/serializers.md → ...docs/dev/learn/subclassing/serializers.md
diff --git a/...-needed!/concepts/subclassing/viewsets.md → ...ng_docs/dev/learn/subclassing/viewsets.md b/...-needed!/concepts/subclassing/viewsets.md → ...ng_docs/dev/learn/subclassing/viewsets.md
diff --git a/...!/concepts/sync_pipeline/sync_pipeline.md → .../dev/learn/sync_pipeline/sync_pipeline.md b/...!/concepts/sync_pipeline/sync_pipeline.md → .../dev/learn/sync_pipeline/sync_pipeline.md
diff --git a/...iage-needed!/concepts/tasks/add-remove.md → staging_docs/dev/learn/tasks/add-remove.md b/...iage-needed!/concepts/tasks/add-remove.md → staging_docs/dev/learn/tasks/add-remove.md
diff --git a/...age-needed!/concepts/tasks/diagnostics.md → staging_docs/dev/learn/tasks/diagnostics.md b/...age-needed!/concepts/tasks/diagnostics.md → staging_docs/dev/learn/tasks/diagnostics.md
diff --git a/.../triage-needed!/concepts/tasks/publish.md → staging_docs/dev/learn/tasks/publish.md b/.../triage-needed!/concepts/tasks/publish.md → staging_docs/dev/learn/tasks/publish.md
diff --git a/staging_docs/dev/tutorials/_SUMMARY.md b/staging_docs/dev/tutorials/_SUMMARY.md
@@ -0,0 +1,2 @@
+* [Contributing with docs](quickstart-docs.md)
+* [Contributing with code](quickstart.md)
diff --git a/..._docs/dev/tutorials/00-quickstart-docs.md → ...ing_docs/dev/tutorials/quickstart-docs.md b/..._docs/dev/tutorials/00-quickstart-docs.md → ...ing_docs/dev/tutorials/quickstart-docs.md
diff --git a/staging_docs/dev/tutorials/01-quickstart.md → staging_docs/dev/tutorials/quickstart.md b/staging_docs/dev/tutorials/01-quickstart.md → staging_docs/dev/tutorials/quickstart.md
diff --git a/staging_docs/sections/admin/index.md b/staging_docs/sections/admin/index.md
diff --git a/staging_docs/sections/development/index.md b/staging_docs/sections/development/index.md
diff --git a/staging_docs/sections/help/bugs-features.md b/staging_docs/sections/help/bugs-features.md
diff --git a/staging_docs/sections/help/index.md b/staging_docs/sections/help/index.md
diff --git a/staging_docs/sections/reference/01-repository-map.md b/staging_docs/sections/reference/01-repository-map.md
diff --git a/staging_docs/sections/reference/02-glossary.md b/staging_docs/sections/reference/02-glossary.md
diff --git a/staging_docs/sections/reference/index.md b/staging_docs/sections/reference/index.md
diff --git a/staging_docs/sections/usage/index.md b/staging_docs/sections/usage/index.md
diff --git a/staging_docs/user/learn/concepts.md b/staging_docs/user/learn/concepts.md
@@ -3,12 +3,12 @@
 This introduction is designed for anyone who is familiar with software management even without prior
 knowledge of Pulp.
 
-From a user’s perspective, Pulp is a tool to manage content. In this context, \_Pulp\_ refers to
+From a user’s perspective, Pulp is a tool to manage content. In this context, *Pulp* refers to
 pulpcore and one or more content plugins.
 
 ## What is pulpcore?
 
-Throughout Pulp documentation, when you see references to \_pulpcore\_, this term refers to the main
+Throughout Pulp documentation, when you see references to *pulpcore*, this term refers to the main
 python program that provides a platform to which you add content plugins for the types of content
 that you want to manage. In a very general sense, Pulpcore refers to Pulp and its functionality
 without any plugins. Pulpcore provides a REST API and a Plugin API.
@@ -21,9 +21,10 @@ install the RPM plugin. Files that belong to a content unit are called
 `Artifacts`. Each content unit can have zero or many artifacts. Artifacts can be
 shared by multiple content units.
 
-```{image} ./_diagrams/concept-content.png
-:align: center
-```
+<figure markdown="span">
+  ![Concept Content](site:pulpcore/docs/assets/images/concept-content.png)
+  <!-- <figcaption>Image caption</figcaption> -->
+</figure>
 
 ## Content repositories and versioning
 
@@ -33,13 +34,15 @@ in a repository. Each time the content of a repository is changed, a new Reposit
 created. Any operation such as sync that does not change the content set, does not produce a new
 repository version.
 
-```{image} ./_diagrams/concept-repository.png
-:align: center
-```
+<figure markdown="span">
+  ![Concept Content](site:pulpcore/docs/assets/images/concept-repository.png)
+  <!-- <figcaption>Image caption</figcaption> -->
+</figure>
 
-```{image} ./_diagrams/concept-add-repo.png
-:align: center
-```
+<figure markdown="span">
+  ![Concept Content](site:pulpcore/docs/assets/images/concept-add-repo.png)
+  <!-- <figcaption>Image caption</figcaption> -->
+</figure>
 
 ## Pulling content into Pulp with Remotes
 
@@ -48,9 +51,10 @@ Through your plugin of choice, you can define actions to interact with those ext
 For example, most or all plugins define sync to fetch content units from a remote and add them to a
 Pulp repository.
 
-```{image} ./_diagrams/concept-remote.png
-:align: center
-```
+<figure markdown="span">
+  ![Concept Content](site:pulpcore/docs/assets/images/concept-remote.png)
+  <!-- <figcaption>Image caption</figcaption> -->
+</figure>
 
 ## Serving content with Pulp
 
@@ -64,6 +68,7 @@ To serve content from Pulp, you need to create a publication and a distribution.
 unit in the content set. To host a publication, it must be assigned to a `Distribution`, which
 determines how and where a publication is served.
 
-```{image} ./_diagrams/concept-publish.png
-:align: center
-```
+<figure markdown="span">
+  ![Concept Content](site:pulpcore/docs/assets/images/concept-publish.png)
+  <!-- <figcaption>Image caption</figcaption> -->
+</figure>
diff --git a/staging_docs/user/tutorials/01-overview.md b/staging_docs/user/tutorials/01-overview.md
diff --git a/staging_docs/user/tutorials/02-setup.md b/staging_docs/user/tutorials/02-setup.md
diff --git a/staging_docs/user/tutorials/03-installation.md b/staging_docs/user/tutorials/03-installation.md
diff --git a/staging_docs/user/tutorials/04-configuration.md b/staging_docs/user/tutorials/04-configuration.md
diff --git a/staging_docs/user/tutorials/05-deployment.md b/staging_docs/user/tutorials/05-deployment.md
diff --git a/staging_docs/user/tutorials/06-conclusion.md b/staging_docs/user/tutorials/06-conclusion.md
diff --git a/staging_docs/user/tutorials/index.md b/staging_docs/user/tutorials/index.md
@@ -0,0 +1,42 @@
+# Start Here
+
+If you are a new user and are unsure where to begin, this page outlines the different options available, as well as the limitations and requirements for those options.
+
+## Want to evaluate Pulp?
+
+The quickest way to evaluate Pulp is by using Pulp in One Container.
+This image contains all the services that you need to run Pulp and is perfect for an initial evaluation.
+Mind that this container cannot scale to provide for high availability scenarios.
+
+For installation instructions, see
+[Pulp in One Container](site:pulp-oci-images/docs/admin/tutorials/quickstart/).
+
+## Is there a Kubernetes/OpenShift deployment option?
+
+Pulp operator endeavours to provide a scalable and robust cluster for Pulp 3.
+Pulp can be installed from [OperatorHub](https://operatorhub.io/operator/pulp-operator).
+If you're interested in providing feedback or contributing to making this better, see the
+[Pulp operator repo](https://github.com/pulp/pulp-operator) on GitHub.
+
+For more information about using Pulp operator, see
+[Pulp on Openshift](site:pulp-operator/docs/admin/tutorials/quickstart-openshift/)
+
+## Is there a podman/docker compose deployment option?
+
+Based on community feedback from the survey and PulpCon 2021, we have reused the Pulp operator images to create a podman compose option for deploying Pulp.
+If you're familiar with podman compose, you can customize the configuration to suit your deployment needs and to deploy at scale.
+
+For more information see our
+[podman/docker compose intro section](site:pulp-oci-images/docs/admin/tutorials/quickstart/#podman-or-docker-compose).
+
+## Do you need something else?
+
+If you are blocked and don't find an option that you need, please post to our [Pulp Community Discourse](https://discourse.pulpproject.org) and let us know what problem you encountered or what scenario you're missing. Feel free to introduce yourself, what you're trying to achieve, where you ran into problems or didn't understand something. We're always happy to hear how people are using Pulp!
+
+You can also find us on [**pulp** on Matrix](https://matrix.to/#/!HWvLQmBGVPfJfTQBAu:matrix.org) for user support.
+
+!!! note
+
+    We plan to write an Introduction Tutorial to teach fundamentals skills and concepts throught a basic Project.
+    Reach out if you have a good idea of what this didactical Project could look like.
+