Copy content to new docs structure

The content was split between pulp-cli and pulp-glue, so they both
have their own namespace in the final documentation website.

closes pulp#903

CHANGES/903.doc

@@ -0,0 +1 @@
+Added the the docs structure and populated with existing content

CHANGES/pulp-glue/903.doc

@@ -0,0 +1 @@
+Added the the docs structure and populated with existing content

pulp-glue/staging_docs/dev/reference/common_context.md

@@ -0,0 +1,3 @@
+# pulp_glue.common.context
+
+::: pulp_glue.common.context

pulp-glue/staging_docs/dev/reference/common_i18n.md

@@ -0,0 +1,3 @@
+# pulp_glue.common.i18n
+
+::: pulp_glue.common.i18n

pulp-glue/staging_docs/dev/reference/common_openapi.md

@@ -0,0 +1,3 @@
+# pulp_glue.common.openapi
+
+::: pulp_glue.common.openapi

pulp-glue/staging_docs/dev/reference/core_context.md

@@ -0,0 +1,3 @@
+# pulp_glue.core.context
+
+::: pulp_glue.core.context

staging_docs/dev/guides/contribute.md

@@ -0,0 +1,77 @@
+# Contribute to the CLI
+
+There are many ways to contribute to this project, and all are welcome.
+
+## Get in Touch
+
+If you want to connect with the Pulp community, ask some not-so-frequently-asked-questions or just leave general feedback, you can reach us in different ways summed up on [pulpproject.org](https://pulpproject.org/get_involved/).
+
+
+## Doc Contributions
+
+If you see something wrong with the docs, we welcome [documentation PRs](https://github.com/pulp/pulp-cli).
+
+If you are using the Pulp CLI and have written end-to-end steps for Pulp workflows, we would greatly appreciate if you would contribute docs to the relevant [plugins](https://docs.pulpproject.org/pulpcore/plugins/index.html).
+
+
+## Code Conventions
+
+If you are interested in contributing code, note that we have styling and formatting
+conventions for both the code and our PRs:
+* `pulp-cli` utilizes python type annotations and black and isort code formatting.
+  To run the auto-formatting features, execute `make black`.
+* To check for compliance, please, install lint requirements and run lint checks before committing changes:
+  ```
+  pip install -r lint_requirements.txt
+  make lint
+  ```
+  * This executes the following checks:
+    * shellcheck
+    * black
+    * isort
+    * flake8
+    * mypy
+* If your PR is in response to an open issue, add `fixes #<ISSUE-NUMBER>` as its own line
+in your commit message. If you do **not** have an issue, use `[noissue]`.
+
+!!!note
+
+   PRs need to pass these checks before they can be merged.
+
+Also please follow [The seven rules of a great Git commit message](https://chris.beams.io/posts/git-commit/).
+And finally, for each new feature, we require corresponding tests.
+
+## Global Help Accessibility
+
+In order to be able to access every (sub-)commands help page,
+it is necessary that no code outside of the final performing command callback accesses the `api` property of the `PulpContext`.
+There are some facilities that perform lazy loading to help with that requirement.
+Those include:
+
+  - `PulpContext.api`: When accessed, the `api.json` file for the addressed server will be read or downloaded and processed.
+    Scheduled version checks will be reevaluated.
+  - `PulpContext.needs_version`: This function can be used at any time to declear that an operation needs a plugin in a version range.
+    The actual check will be performed, once `api` was accessed for the first time, or immediately afterwards.
+  - `PulpEntityContext.entity`: This property can be used to collect lookup attributes for entities by assigining dicts to it.
+    On read access, the entity lookup will be performed though the `api` property.
+  - `PulpEntityContext.pulp_href`: This property can be used to specify an entity by its URI.
+    It will be fetched from the server only at read access.
+
+## Testing
+
+Tests are shell scripts in `tests/scripts` with names like `test_*.sh`.
+They should should focus on the cli operation and are not a replacement for pulp integration tests;
+i.e. make sure the cli translates to the right api calls, but do not care about pulp internals.
+
+## Running Tests
+
+In order to run tests, a running instance of pulp with all necessary plugins installed must be
+configured in `tests/cli.toml`.
+
+To run tests:
+
+```
+make test                           # all tests
+pytest -m pulp_file                 # tests for pulp_file
+pytest -m pulp_file -k test_remote  # run tests/scripts/pulp_file/test_remote.sh
+```

staging_docs/dev/learn/architecture.md

@@ -0,0 +1,115 @@
+## Architecture
+
+The Pulp CLI architecture is described in this section.
+
+### Plugin System
+
+The Pulp CLI is designed with a plugin structure. Plugins can either live in the pulp-cli package or be shipped independently.
+By convention, all parts of the CLI are packages in the open namespace `pulpcore.cli`.
+A plugin can register itself with the main app by specifying by specifying its main module as a `pulp_cli.plugins` entrypoint in `setup.py`.
+
+```python
+entry_points={
+    "pulp_cli.plugins": [
+        "myplugin=pulpcore.cli.myplugin",
+    ],
+}
+```
+
+The plugin can then attach subcommands to the `pulpcore.cli.common.main` command by providing a `mount` method in the main module.
+
+```python
+from pulpcore.cli.common.generic import pulp_command
+
+@pulp_command()
+def my_command():
+    pass
+
+
+def mount(main: click.Group, **kwargs: Any) -> None:
+    main.add_command(my_command)
+```
+
+### Contexts
+
+In `click`, every subcommand is accompanied by a `click.Context`, and objects can be attached to them.
+In this CLI we attach a `PulpContext` to the main command.
+It acts as an abstraction layer that handles the communication to the pulp server through its `api` property.
+Further we encourage the handling of communication with certain endpoints by subclassing the `PulpEntityContext`.
+By attaching them to the contexts of certain command groups, they are accessible to commands via the `pass_entity_context` decorator.
+Those entity contexts should provide a common interface to the layer of `click` commands that define the user interaction.
+
+```python
+@pulp_group()
+@pass_pulp_context
+@click.pass_context
+def my_command(ctx, pulp_ctx):
+    ctx.obj = MyEntityContext(pulp_ctx)
+
+
+@my_command.command()
+@pass_entity_context
+def my_sub_command(entity_ctx):
+    ... href = ...
+    entity_ctx.destroy(href)
+```
+
+### Version dependent code paths
+
+Each Pulp CLI release is designed to support multiple Pulp server versions and the CLI itself is versioned independently of any version of the Pulp server components.
+It is supposed to be able to communicate with different combinations of server component versions at the same time.
+Because of this, it might be necessary to guard certain features and workarounds by checking against the available server plugin version.
+As a rule of thumb, all necessary workarounds should be implemented in the corresponding `Context` objects to provide a consistent interface to the command callbacks.
+To facilitate diverting code paths depending on plugin versions, the `PulpContext` provides the `needs_plugin` and `has_plugin` methods.
+While `has_plugin` will evaluete immediately, `needs_plugin` can be seen as a deferred assertion.
+It will raise an error, once the first access to the server is attempted.
+
+```python
+class MyEntityContext(PulpEntityContext):
+    def show(self, href):
+        if self.pulp_ctx.has_plugin(PluginRequirement("my_content", specifier=">=1.2.3", inverted=True)):
+            # Versioned workaroud
+            # see bug-tracker/12345678
+            return lookup_my_content_legacy(href)
+        return super().show(href)
+
+
+@main.command()
+@pass_pulp_context
+@click.pass_context
+def my_command(ctx, pulp_ctx):
+    pulp_ctx.needs_plugin(PluginRequirement("my_content", specifier=">=1.0.0"))
+    ctx.obj = MyEntityContext(pulp_ctx)
+```
+
+The named tuple `PluginRequirement` is used to describe dependence on server components.
+It needs the `name` of the plugin and accepts optionally an inclusive `min` version,
+an exclusive `max` version, and an `inverted` flag for exclusion of a version range.
+
+Additionally, the `PulpOption` provides the `needs_plugins` keyword argument.
+It accepts a list of `PluginRequirements` to error when used.
+
+### Generics
+
+For certain often repeated patterns like listing all entities of a particular kind,
+we provide generic commands that use the underlying context objects.
+
+```python
+from pulpcore.cli.common.generic import name_option, show_command,
+
+lookup_params = [name_option]
+my_command.add_command(show_command(decorators=lookup_params))
+```
+
+Some of these commands understand extra arguments.
+They can be attached by passing a list of `click.Options` via the `decorators` argument.
+
+```python
+from pulpcore.cli.common.generic import list_command,
+
+filter_params = [
+    click.option("--name"),
+    click.option("--name-contains", "name__contains"),
+]
+my_command.add_command(list_command(decorators=filter_params))
+```

staging_docs/dev/reference/common_generic.md

@@ -0,0 +1,3 @@
+# pulpcore.cli.common.generic
+
+::: pulpcore.cli.common.generic

staging_docs/user/guides/advanced_features.md

@@ -0,0 +1,60 @@
+# Advanced features
+
+## Custom CA bundle
+
+You can specify a custom CA bundle for the connection to a Pulp server by providing a path in one of the following environment variables (ordered by precedence):
+`PULP_CA_BUNDLE` ,`REQUESTS_CA_BUNDLE` `CURL_CA_BUNDLE`
+
+## Shell Completion
+
+The CLI uses the click package which supports shell completion.
+To configure this, check out [click's documentation](https://click.palletsprojects.com/en/8.0.x/shell_completion/).
+As an example, here is what to add to your `~/.bashrc` file if you're using bash:
+
+```bash
+eval "$(LC_ALL=C _PULP_COMPLETE=bash_source pulp)"
+```
+
+!!! note
+
+    When using `click<8.0.0` the command instead reads:
+
+    `eval "$(LC_ALL=C _PULP_COMPLETE=source_bash pulp)"`
+
+## Interactive shell mode
+
+* To use the shell mode, you need to install the the extra requirements tagged "shell". *
+
+Starting the CLI with "pulp shell" drops you into the shell:
+```plain
+(pulp) [vagrant@pulp3 ~]$ pulp shell
+Starting Pulp3 interactive shell...
+pulp> help
+
+Documented commands (type help <topic>):
+========================================
+access-policy  config     export    group      orphans     rpm     task
+ansible        container  exporter  importer   python      show    user
+artifact       debug      file      migration  repository  status  worker
+
+Undocumented commands:
+======================
+exit  help  quit
+
+pulp> status
+{
+    ...
+}
+
+pulp> exit
+(pulp) [vagrant@pulp3 ~]$
+```
+
+Issuing the command with arguments works as it does currently:
+```plain
+(pulp) [vagrant@pulp3 ~]$ pulp status
+{
+    ...
+}
+(pulp) [vagrant@pulp3 ~]$
+```

staging_docs/user/guides/configure.md

@@ -0,0 +1,81 @@
+# Configure
+
+The CLI can be configured by using a toml file.
+By default the location of this file is `~/.config/pulp/cli.toml`.
+However, this can be customized by using the `--config` option.
+Any settings supplied as options to a command will override these settings.
+
+Example file:
+
+```
+[cli]
+base_url = "https://pulp.dev"
+verify_ssl = false
+format = "json"
+```
+
+## Config Profiles
+
+The CLI allows you to configure additional profiles at the same time.
+If you add a `[cli-server1]` section to your config,
+you can use that set of settings by specifying the `--profile server1` on the pulp command line.
+This can be helpful if you need to use different usernames for certain actions,
+or if you need to interact with several different Pulp servers.
+
+## Generating a new configuration
+
+To generate a new configuration:
+
+```
+pulp config create --base-url "http://localhost"
+pulp config create -e  # with an editor (e.g. vim)
+pulp config create -i  # interactive prompts
+```
+
+## Validating the configuration
+
+The easiest way to validate your config is to call a command that interacts with your Pulp server:
+
+```
+pulp status
+```
+
+To statically validate your config file (check that it exists, that it has not erroneous values,
+etc) use the validate command:
+
+```
+pulp config validate
+pulp config validate --strict  # validates that all settings are present
+```
+
+## Using netrc
+
+If no user/pass is supplied either in the config file or as an option,
+then the CLI will attempt to use `~/.netrc`.
+Here is a `.netrc` example for localhost:
+
+```
+machine localhost
+login admin
+password password
+```
+
+## Tips for Katello Users
+
+If you have a Katello environment and wish to use pulp-cli to connect to Pulp, you'll need to
+configure client certificate authentication in your `~/.config/pulp/cli.toml`:
+
+```toml
+[cli]
+base_url = "https://<your FQDN>"
+cert = "/etc/pki/katello/certs/pulp-client.crt"
+key = "/etc/pki/katello/private/pulp-client.key"
+```
+
+Katello content-proxy servers do not possess the certificates required to communicate with Pulp;
+therefore you should install pulp-cli only on the primary server, and override the `base_url` setting on the command line when you need to connect to Pulp running on a content-proxy rather than Pulp on the primary Katello server: `--base-url https://capsule.example.com`
+It can be helpful to use the `--profile` option here.
+
+As Katello uses Pulp as a backend, all modifying actions in Pulp should be performed via Katello.
+Therefore you are also strongly encourged to set `dry_run = true`, to prevent accidentally calling into dangerous commands.
+This setting can in turn be overwritten on the command-line with the `--force` flag.