Improve User/Admin guides and write dev quickstarts

- Rename guides for User and Admin to comply with a similar Title style
- Apply some reformatting/re-styling with mkdocs features
- Write quickstarts to contributing with docs and code

[noissue]

staging_docs/admin/guides/authentication/01-overview.md

@@ -1,13 +1,11 @@
-
-
 # Overview
 
 By default, Pulp supports Basic and Session authentication. The Basic Authentication checks the
 username and password against the internal users database.
 
 !!! note
-This authentication is only for the REST API. Clients fetching binary data have their identity
-verified and authorization checked using a `ContentGuard`.
+    This authentication is only for the REST API. Clients fetching binary data have their identity
+    verified and authorization checked using a `ContentGuard`.
 
 
 ## Which URLs Require Authentication?
@@ -21,7 +19,7 @@ Authentication in Pulp is provided by Django Rest Framework and Django together.
 Django provides the [AUTHENTICATION_BACKENDS](https://docs.djangoproject.com/en/4.2/ref/settings/#std:setting-AUTHENTICATION_BACKENDS) which defines a set of behaviors to check usernames and
 passwords against. By default it is set to:
 
-```
+```python
 AUTHENTICATION_BACKENDS = [
     'django.contrib.auth.backends.ModelBackend',  # Django's users, groups, and permissions
     'pulpcore.backends.ObjectRolePermissionBackend'  # Pulp's RBAC object and model permissions
@@ -31,11 +29,19 @@ AUTHENTICATION_BACKENDS = [
 Django Rest Framework defines the source usernames and passwords come from with the
 [DEFAULT_AUTHENTICATION_CLASSES](https://www.django-rest-framework.org/api-guide/authentication/#setting-the-authentication-scheme) setting. By default it is set to:
 
-```
+```python
 REST_FRAMEWORK = {
     'DEFAULT_AUTHENTICATION_CLASSES': [
         'rest_framework.authentication.SessionAuthentication',  # Session Auth
         'rest_framework.authentication.BasicAuthentication'  # Basic Auth
     ]
 }
 ```
+
+## Extend
+
+Pulp is a Django app and Django Rest Framework (DRF) application, so additional authentication can
+be added as long as it's correctly configured for both Django and Django Rest Frameowork.
+
+See the [Django docs on configuring custom authentication](https://docs.djangoproject.com/en/4.2/topics/auth/customizing/#customizing-authentication-in-django) and the [Django Rest Framework docs
+on configuring custom authentication](https://www.django-rest-framework.org/api-guide/authentication/#custom-authentication).

staging_docs/admin/guides/authentication/02-basic.md

@@ -1,6 +1,4 @@
-
-
-# Basic
+# Authenticate using basic credentials
 
 Pulp by default uses [Basic Authentication](https://tools.ietf.org/html/rfc7617) which checks the
 user submitted header against an internal database of users. If the username and password match, the
@@ -29,12 +27,12 @@ http Authorization:"Basic YWRtaW46cGFzc3dvcmQ=" ...
 ```
 
 !!! warning
-For the 3.y releases, Pulp expects the user table to have exactly 1 user in it named 'admin',
-which is created automatically when the initial migration is applied. The password for this user
-can be set with the `pulpcore-manager reset-admin-password` command.
-To articulate what you'd like to see future versions of Pulp file a feature request
-[here](https://github.com/pulp/pulpcore/issues) or reach out via
-[[email protected]](https://www.redhat.com/mailman/listinfo/pulp-list).
+    For the 3.y releases, Pulp expects the user table to have exactly 1 user in it named 'admin',
+    which is created automatically when the initial migration is applied. The password for this user
+    can be set with the `pulpcore-manager reset-admin-password` command.
+    To articulate what you'd like to see future versions of Pulp file a feature request
+    [here](https://github.com/pulp/pulpcore/issues) or reach out via
+    [[email protected]](https://www.redhat.com/mailman/listinfo/pulp-list).
 
 
 ## Disabling Basic Authentication

staging_docs/admin/guides/authentication/03-webserver.md

@@ -1,15 +1,16 @@
-
-
-# Webserver
+# Authenticate using external service
 
 Pulp can be configured to use authentication provided in the webserver outside of Pulp. This allows
 for integration with ldap for example, through [mod_ldap](https://httpd.apache.org/docs/2.4/mod/mod_ldap.html), or certificate based API access, etc.
 
-Enable external authentication in two steps:
+## Enable external Auth
+
+### 1. Accept external Auth
 
-1\. Accept external auth instead of checking the internal users database by setting the
-`AUTHENTICATION_BACKENDS` to `['django.contrib.auth.backends.RemoteUserBackend']`. This will
-cause Pulp to accept any username for each request and by default create a user in the database
+Accept external auth instead of checking the internal users database by setting the
+`AUTHENTICATION_BACKENDS` to `['django.contrib.auth.backends.RemoteUserBackend']`.
+
+This will cause Pulp to accept any username for each request and by default create a user in the database
 backend for them. To have any name accepted but not create the user in the database backend, use the
 `pulpcore.app.authentication.PulpNoCreateRemoteUserBackend` instead.
 
@@ -23,15 +24,17 @@ to authenticated users specify set `DEFAULT_PERMISSION_CLASSES` to
 `rest_framework.permissions.IsAuthenticated`. Alternatively, to allow any user (even
 unauthenticated) use `rest_framework.permissions.AllowAny`.
 
-2. Specify how to receive the username from the webserver. Do this by specifying to DRF an
-   `DEFAULT_AUTHENTICATION_CLASSES`. For example, consider this example:
+### 2. Configure 
+
+Specify how to receive the username from the webserver. Do this by specifying to DRF an
+`DEFAULT_AUTHENTICATION_CLASSES`. For example, consider this example:
 
-   ```
-   REST_FRAMEWORK['DEFAULT_AUTHENTICATION_CLASSES'] = (
-       'rest_framework.authentication.SessionAuthentication',
-       'pulpcore.app.authentication.PulpRemoteUserAuthentication'
-   )
-   ```
+ ```python
+ REST_FRAMEWORK['DEFAULT_AUTHENTICATION_CLASSES'] = (
+     'rest_framework.authentication.SessionAuthentication',
+     'pulpcore.app.authentication.PulpRemoteUserAuthentication'
+ )
+ ```
 
 This removes `rest_framework.authentication.BasicAuthentication`, but retains
 `rest_framework.authentication.SessionAuthentication` and adds
@@ -89,6 +92,6 @@ Pulp provides a setting named `REMOTE_USER_ENVIRON_NAME <remote-user-environ-nam
 you to specify another WSGI environment variable to read the authenticated username from.
 
 !!! warning
-Configuring this has serious security implications. See the [Django warning at the end of this
-section in their docs](https://docs.djangoproject.com/en/4.2/howto/auth-remote-user/#configuration) for more details.
+    Configuring this has serious security implications. See the [Django warning at the end of this
+    section in their docs](https://docs.djangoproject.com/en/4.2/howto/auth-remote-user/#configuration) for more details.
 

staging_docs/admin/guides/authentication/04-keycloak.md

@@ -1,6 +1,4 @@
-
-
-# Keycloak
+# Authenticate using Keycloak
 
 Pulp can be configured to use authentication provided by a Keycloak server outside of Pulp.
 [Keycloak](https://www.keycloak.org/) can provide Identity Brokering, User Federation, Single
@@ -14,7 +12,7 @@ The library that will be utilized for the integration between Keycloak and Pulp
 [python-social-auth](https://python-social-auth.readthedocs.io/en/latest/index.html). The
 following python modules must be installed in order to make use of python-social-auth within Pulp:
 
-```
+```bash
 social-auth-core
 social-auth-app-Django
 ```
@@ -28,60 +26,66 @@ describes the django updates necessary to configure social-auth.
 
 Enable general python social integration with the following steps:
 
-1. Add the application to INSTALLED_APPS setting:
+### 1. Add the application to INSTALLED_APPS
 
-   ```
-   INSTALLED_APPS = (
-       ...
-       'social_django',
-       ...
-   )
-   ```
+```python title="settings.py"
+INSTALLED_APPS = (
+   ...
+   'social_django',
+   ...
+)
+```
 
-2. Accept Keycloak auth instead of checking the internal users database by enabling:
+### 2. Accept Keycloak auth
 
-   ```
-   AUTHENTICATION_BACKENDS = [
-       ...
-       'social_core.backends.keycloak.KeycloakOAuth2',
-       ...
-   ]
-   ```
+Accept Keycloak auth instead of checking the internal users database by enabling:
 
-3. Update the context processor that will add backends and associations data to the template context:
+```python title="settings.py"
+AUTHENTICATION_BACKENDS = [
+   ...
+   'social_core.backends.keycloak.KeycloakOAuth2',
+   ...
+]
+```
 
-   ```
-   TEMPLATES = [
-       {
+### 3. Update the context processor
+
+Update the context processor that will add backends and associations data to the template context:
+
+```python title="settings.py"
+TEMPLATES = [
+   {
+       ...
+       'OPTIONS': {
            ...
-           'OPTIONS': {
+           'context_processors': [
+               ...
+               'social_django.context_processors.backends',
+               'social_django.context_processors.login_redirect',
                ...
-               'context_processors': [
-                   ...
-                   'social_django.context_processors.backends',
-                   'social_django.context_processors.login_redirect',
-                   ...
-               ]
-           }
+           ]
        }
-   ]
-   ```
-
-4. Define the authentication pipeline for data that will be associated with users:
+   }
+]
+```
 
-   ```
-   SOCIAL_AUTH_PIPELINE = (
-       'social_core.pipeline.social_auth.social_details',
-       'social_core.pipeline.social_auth.social_uid',
-       'social_core.pipeline.social_auth.social_user',
-       'social_core.pipeline.user.get_username',
-       'social_core.pipeline.social_auth.associate_by_email',
-       'social_core.pipeline.user.create_user',
-       'social_core.pipeline.social_auth.associate_user',
-       'social_core.pipeline.social_auth.load_extra_data',
-       'social_core.pipeline.user.user_details',
-   )
-   ```
+### 4. Define the authentication pipeline
+
+Define the authentication pipeline for data that will be associated with users:
+
+```python title="settings.py"
+SOCIAL_AUTH_PIPELINE = (
+   'social_core.pipeline.social_auth.social_details',
+   'social_core.pipeline.social_auth.social_uid',
+   'social_core.pipeline.social_auth.social_user',
+   'social_core.pipeline.user.get_username',
+   'social_core.pipeline.social_auth.associate_by_email',
+   'social_core.pipeline.user.create_user',
+   'social_core.pipeline.social_auth.associate_user',
+   'social_core.pipeline.social_auth.load_extra_data',
+   'social_core.pipeline.user.user_details',
+)
+```
 
 
 
@@ -93,54 +97,58 @@ describes the necessary Keycloak integration variables.
 
 Enable python social and Keycloak integration with the following steps:
 
-1. On your Keycloak server, create a Realm (pulp)
+1) On your Keycloak server, create a Realm (pulp)
+
+2) Create a Client in the new Realm
 
-2. Create a Client in the new Realm
+3) Configure the Client `Access Type` to be "confidential.
 
-3. Configure the Client `Access Type` to be "confidential. Provide `` Valid Redirect URIs` `` with
-   `http://<pulp-hostname>:<port>/*`. Set the `User Info Signed Response Algorithm` and
-   `Request Object Signature Algorithm` is set to `RS256` in the
-   `Fine Grain OpenID Connect Configuration` section
+Provide `` Valid Redirect URIs` `` with
+ `http://<pulp-hostname>:<port>/*`. Set the `User Info Signed Response Algorithm` and
+ `Request Object Signature Algorithm` is set to `RS256` in the
+ `Fine Grain OpenID Connect Configuration` section
 
-4. In the Pulp settings, add the value for the `Client ID`:
+4) In the Pulp settings, add the value for the `Client ID`:
 
-   ```
-   SOCIAL_AUTH_KEYCLOAK_KEY = '<Client ID>'
-   ```
+ ```
+ SOCIAL_AUTH_KEYCLOAK_KEY = '<Client ID>'
+ ```
 
-5. Gather the `Client Secret` for the Pulp settings. You can find the `Client Secret` in the
+5) Gather the `Client Secret` for the Pulp settings. You can find the `Client Secret` in the
    Credentials tab:
 
-   ```
-   SOCIAL_AUTH_KEYCLOAK_SECRET = '<Client Secret>'
-   ```
+ ```
+ SOCIAL_AUTH_KEYCLOAK_SECRET = '<Client Secret>'
+ ```
 
-6. Collect the `Public Key` from the Realm's Keys tab:
+6) Collect the `Public Key` from the Realm's Keys tab:
 
-   ```
-   SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY = '<Public Key>'
-   ```
+ ```
+ SOCIAL_AUTH_KEYCLOAK_PUBLIC_KEY = '<Public Key>'
+ ```
 
-7. Add the `authorization_endpoint` and `token_endpoint` URL that you find to the Realm OpenID Endpoint
+7) Add the `authorization_endpoint` and `token_endpoint` URL that you find to the Realm OpenID Endpoint
    Configuration to the Pulp settings:
 
-   ```
-   SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL = \
-       'https://iam.example.com/auth/realms/pulp/protocol/openid-connect/auth/'
-   SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL = \
-       'https://iam.example.com/auth/realms/pulp/protocol/openid-connect/token/'
-   ```
-
-8. Create an audience mapper for the JWT token. In the Client, select the Mappers tab, select
-   the Create button to create a Mapper. Name the mapper, for example, "Audience Mapper". From
-   the `Mapper Type` list, select "Audience". Define the `Included Client Audience` to be the
-   `Client ID`. Enable this for both the ID token and access token.
-
-9. Add additional Built-in Mappers to the JWT to populate the token with the data defined in the
-   Social Auth Pipeline. To do this, in the Client again select the Mappers tab. Next select the
-   "Add Builtin" button and you will be presented with a table of mappers that can be chosen.
-   Common choices are `username`, `email`, `groups`, `given name`, `family name`,
-   `full name`, `updated at`, and `email verified`.
+ ```
+ SOCIAL_AUTH_KEYCLOAK_AUTHORIZATION_URL = \
+     'https://iam.example.com/auth/realms/pulp/protocol/openid-connect/auth/'
+ SOCIAL_AUTH_KEYCLOAK_ACCESS_TOKEN_URL = \
+     'https://iam.example.com/auth/realms/pulp/protocol/openid-connect/token/'
+ ```
+
+8) Create an audience mapper for the JWT token.
+
+In the Client, select the Mappers tab, select the Create button to create a Mapper. Name the mapper, for example, "Audience Mapper".
+From the `Mapper Type` list, select "Audience". Define the `Included Client Audience` to be the `Client ID`.
+Enable this for both the ID token and access token.
+
+9) Add additional Built-in Mappers to the JWT to populate the token with the data defined in the Social Auth Pipeline.
+
+To do this, in the Client again select the Mappers tab. Next select the
+"Add Builtin" button and you will be presented with a table of mappers that can be chosen.
+Common choices are `username`, `email`, `groups`, `given name`, `family name`,
+`full name`, `updated at`, and `email verified`.
 
 After setup is completed go to: `http://<pulp-hostname>:<port>/login/keycloak` and the login flow
 will be presented.