diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 03f160e78..000000000 --- a/docs/Makefile +++ /dev/null @@ -1,199 +0,0 @@ -# WARNING: DO NOT EDIT! -# -# This file was generated by plugin_template, and is managed by it. Please use -# './plugin-template --docs pulp_ansible' to update this file. -# -# For more info visit https://github.com/pulp/plugin_template -# Makefile for Sphinx documentation -# - -SHELL := /bin/bash -# You can set these variables from the command line. -SPHINXOPTS = -W # turn warnings into errors -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build -DIAGRAM_BUILD_DIR = _diagrams -PULP_URL ?= http://localhost:24817 -PULP_API_ROOT ?= /pulp/ - -# Internal variables. -PULP_V3_API_JSON_URL := ${PULP_URL}${PULP_API_ROOT}api/v3/docs/api.json -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext diagrams - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " diagrams to make diagram images" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - -rm -rf $(BUILDDIR)/* - -rm -rf $(DIAGRAM_BUILD_DIR)/* - -install: - python3 -m venv pulpdocs - source pulpdocs/bin/activate && pip install -r ../doc_requirements.txt - -diagrams: -ifneq ($(wildcard diagrams_src), ) - mkdir -p $(DIAGRAM_BUILD_DIR) -ifneq ("$(wildcard pulpdocs/bin/activate)","") - source pulpdocs/bin/activate && python3 -m plantuml diagrams_src/*.dot -else - python3 -m plantuml diagrams_src/*.dot -endif - mv diagrams_src/*.png $(DIAGRAM_BUILD_DIR)/ -else - @echo "Did not find $(DIAGRAM_SOURCE_DIR)." -endif - -$(BUILDDIR)/html/api.json: - mkdir -p $(BUILDDIR)/html - if pulp debug has-plugin --name core --specifier ">=3.44.0.dev"; \ - then \ - curl --fail -o $(BUILDDIR)/html/api.json "$(PULP_V3_API_JSON_URL)?component=ansible&include_html=1"; \ - else \ - curl --fail -o $(BUILDDIR)/html/api.json "$(PULP_V3_API_JSON_URL)?plugin=pulp_ansible&include_html=1"; \ - fi - -html: $(BUILDDIR)/html/api.json - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: -ifneq ("$(wildcard pulpdocs/bin/activate)","") - source pulpdocs/bin/activate && PULP_CONTENT_ORIGIN=localhost $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml -else - PULP_CONTENT_ORIGIN=localhost $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml -endif - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PulpDocs.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PulpDocs.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/PulpDocs" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/PulpDocs" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -run: - cd $(BUILDDIR) && python -m http.server 8010 diff --git a/docs/_scripts/distribution_repo.sh b/docs/_scripts/distribution_repo.sh deleted file mode 100755 index 0636ccb50..000000000 --- a/docs/_scripts/distribution_repo.sh +++ /dev/null @@ -1,3 +0,0 @@ -# Distributions are created asynchronously. Create one, and specify the repository that will -# be served at the base path specified. -pulp ansible distribution create --name "baz" --base-path "my_content" --repository "foo" diff --git a/docs/_scripts/distribution_repo_version.sh b/docs/_scripts/distribution_repo_version.sh deleted file mode 100755 index ba18ac9db..000000000 --- a/docs/_scripts/distribution_repo_version.sh +++ /dev/null @@ -1,3 +0,0 @@ -# Distributions are created asynchronously. Create one, and specify the repository version that will -# be served at the base path specified. -pulp ansible distribution create --name "bar" --base-path "some_content" --repository "foo" --version 0 diff --git a/docs/_scripts/quickstart.sh b/docs/_scripts/quickstart.sh deleted file mode 100755 index 32f41d97e..000000000 --- a/docs/_scripts/quickstart.sh +++ /dev/null @@ -1,17 +0,0 @@ -# This script will execute the component scripts and ensure that the documented examples -# work as expected. - -# From the _scripts directory, run with `source quickstart.sh` (source to preserve the environment -# variables) -source setup.sh - -echo "Role - Workflows" -source repo.sh -source distribution_repo.sh -source distribution_repo_version.sh -source remote.sh -source sync.sh - -echo "Collection - Workflows" -source remote-collection.sh -source sync-collection.sh diff --git a/docs/_scripts/remote-collection-token.sh b/docs/_scripts/remote-collection-token.sh deleted file mode 100755 index 3dc89b0cc..000000000 --- a/docs/_scripts/remote-collection-token.sh +++ /dev/null @@ -1,8 +0,0 @@ -# Create a remote that syncs some versions of django into your repository. -pulp ansible remote -t "collection" create \ - --name "abar" \ - --auth-url "https://sso.qa.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token" \ - --token "$ANSIBLE_TOKEN_AUTH" \ - --tls-validation false \ - --url "https://cloud.redhat.com/api/automation-hub/" \ - --requirements $'collections:\n - testing.ansible_testing_content' diff --git a/docs/_scripts/remote-collection.sh b/docs/_scripts/remote-collection.sh deleted file mode 100755 index 0248540ee..000000000 --- a/docs/_scripts/remote-collection.sh +++ /dev/null @@ -1,7 +0,0 @@ -# Create a remote that syncs some versions of django into your repository. -pulp ansible remote -t "collection" create \ - --name "cbar" \ - --url "https://galaxy-dev.ansible.com/" \ - --requirements $'collections:\n - testing.ansible_testing_content' -# If requirements are in a file -# you can use the option '--requirements @' instead. diff --git a/docs/_scripts/remote.sh b/docs/_scripts/remote.sh deleted file mode 100755 index 0e874ee49..000000000 --- a/docs/_scripts/remote.sh +++ /dev/null @@ -1,2 +0,0 @@ -# Create a remote that syncs some versions of django into your repository. -pulp ansible remote -t "role" create --name "bar" --url "https://galaxy.ansible.com/api/v1/roles/?owner__username=elastic" diff --git a/docs/_scripts/repo.sh b/docs/_scripts/repo.sh deleted file mode 100755 index 621e9a24b..000000000 --- a/docs/_scripts/repo.sh +++ /dev/null @@ -1,2 +0,0 @@ -# Start by creating a new repository named foo -pulp ansible repository create --name "foo" diff --git a/docs/_scripts/setup.sh b/docs/_scripts/setup.sh deleted file mode 100755 index 25ca119b9..000000000 --- a/docs/_scripts/setup.sh +++ /dev/null @@ -1,23 +0,0 @@ -#!/usr/bin/env bash -set -e - -export BASE_ADDR=${BASE_ADDR:-http://pulp:80} - -if [ -z "$(pip freeze | grep pulp-cli)" ]; then - echo "Installing pulp-cli" - pip install pulp-cli[pygments] -fi - -# Set up CLI config file -if [ ! -f ~/.config/pulp/settings.toml ]; then - echo "Configuring pulp-cli" - mkdir -p ~/.config/pulp - cat > ~/.config/pulp/cli.toml << EOF -[cli] -base_url = "$BASE_ADDR" -verify_ssl = false -format = "json" -username = "admin" -password = "password" -EOF -fi diff --git a/docs/_scripts/sync-collection.sh b/docs/_scripts/sync-collection.sh deleted file mode 100644 index c083662e1..000000000 --- a/docs/_scripts/sync-collection.sh +++ /dev/null @@ -1,9 +0,0 @@ -# Sync repository foo using remote cbar -pulp ansible repository sync --name "foo" --remote "cbar" - -# Use the -b option to have the sync task complete in the background -# e.g. pulp -b ansible repository sync --name "foo" --remote "cbar" - -# After the task is complete, it gives us a new repository version -# Inspecting new repository version -pulp ansible repository version show --repository "foo" diff --git a/docs/_scripts/sync.sh b/docs/_scripts/sync.sh deleted file mode 100755 index f81e0c65d..000000000 --- a/docs/_scripts/sync.sh +++ /dev/null @@ -1,9 +0,0 @@ -# Sync repository foo using remote bar -pulp ansible repository sync --name "foo" --remote "role:bar" - -# Use the -b option to have the sync task complete in the background -# e.g. pulp -b ansible repository sync --name "foo" --remote "bar" - -# After the task is complete, it gives us a new repository version -# Inspecting new repository version -pulp ansible repository version show --repository "foo" --version 1 diff --git a/docs/_templates/restapi.html b/docs/_templates/restapi.html deleted file mode 100644 index 11943aad2..000000000 --- a/docs/_templates/restapi.html +++ /dev/null @@ -1,24 +0,0 @@ - - - - REST API for Pulp 3 ansible Plugin - - - - - - - - - - - - - diff --git a/docs/static/.gitkeep b/docs/admin/guides/.gitkeep similarity index 100% rename from docs/static/.gitkeep rename to docs/admin/guides/.gitkeep diff --git a/staging_docs/admin/guides/.gitkeep b/docs/admin/learn/.gitkeep similarity index 100% rename from staging_docs/admin/guides/.gitkeep rename to docs/admin/learn/.gitkeep diff --git a/staging_docs/admin/learn/.gitkeep b/docs/admin/reference/.gitkeep similarity index 100% rename from staging_docs/admin/learn/.gitkeep rename to docs/admin/reference/.gitkeep diff --git a/staging_docs/admin/reference/settings.md b/docs/admin/reference/settings.md similarity index 100% rename from staging_docs/admin/reference/settings.md rename to docs/admin/reference/settings.md diff --git a/staging_docs/admin/reference/.gitkeep b/docs/admin/tutorials/.gitkeep similarity index 100% rename from staging_docs/admin/reference/.gitkeep rename to docs/admin/tutorials/.gitkeep diff --git a/docs/bindings.rst b/docs/bindings.rst deleted file mode 100644 index b4b39dfd2..000000000 --- a/docs/bindings.rst +++ /dev/null @@ -1,76 +0,0 @@ -Client Bindings -=============== - -Python Client -------------- - -The `pulp-ansible-client package `_ on PyPI provides -bindings for all API calls in the `pulp_ansible API documentation <../restapi.html>`_. It is -currently published daily and with every RC. - -The `pulpcore-client package `_ on PyPI provides bindings -for all API calls in the `pulpcore API documentation `_. It is currently published daily and with every RC. - - -Ruby Client ------------ - -The `pulp_ansible_client Ruby Gem `_ on rubygems.org -provides bindings for all API calls in the `pulp_ansible API documentation <../restapi.html>`_. It -is currently published daily and with every RC. - -The `pulpcore_client Ruby Gem `_ on rubygems.org provides -bindings for all API calls in the `pulpcore API documentation `_. It is currently published daily and with every RC. - - -Client in a language of your choice ------------------------------------ - -A client can be generated using Pulp's OpenAPI schema and any of the available `generators -`_. - -Generating a client is a two step process: - -**1) Download the OpenAPI schema for pulpcore and all installed plugins:** - -.. code-block:: bash - - curl -o api.json http://:24817/pulp/api/v3/docs/api.json - -The OpenAPI schema for a specific plugin can be downloaded by specifying the plugin's module name -as a GET parameter. For example for ``pulp_ansible`` only endpoints use a query like this: - -.. code-block:: bash - - curl -o api.json http://:24817/pulp/api/v3/docs/api.json?plugin=pulp_ansible - -**2) Generate a client using openapi-generator.** - -The schema can then be used as input to the openapi-generator-cli. The documentation on getting -started with openapi-generator-cli is available on -`openapi-generator.tech `_. - - -Generating a client on dev environment --------------------------------------- - -Pulp dev environment provided by `pulp_installer `_ -introduces a set of useful -`aliases `_, -like `pbindings`. - -Examples: - -- generating python bindings for pulp_ansible: - -.. code-block:: bash - - pbindings pulp_ansible python - -- generating ruby bindings for pulp_ansible with '3.0.0rc1.dev.10' version - -.. code-block:: bash - - pbindings pulp_ansible ruby 3.0.0rc1.dev.10 diff --git a/docs/changes.rst b/docs/changes.rst deleted file mode 100644 index 96e8eb90c..000000000 --- a/docs/changes.rst +++ /dev/null @@ -1,4 +0,0 @@ -Changes -********* - -Removed due to docs migration process. diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100755 index 99b658106..000000000 --- a/docs/conf.py +++ /dev/null @@ -1,289 +0,0 @@ -# WARNING: DO NOT EDIT! -# -# This file was generated by plugin_template, and is managed by it. Please use -# './plugin-template --docs pulp_ansible' to update this file. -# -# For more info visit https://github.com/pulp/plugin_template -# This file is execfile()d with the current directory set to its containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -import os -import sys -from datetime import date - -try: - import sphinx_rtd_theme -except ImportError: - sphinx_rtd_theme = False - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('./extensions')) # noqa - -sys.path.insert(0, os.path.abspath('..')) # noqa - - -# Set environment variable so Sphinx can bootstrap the Django app -os.environ["DJANGO_SETTINGS_MODULE"] = "pulpcore.app.settings" - -import django -django.setup() - -# -- General configuration ----------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [ - 'sphinx.ext.extlinks', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.napoleon', - 'sphinxcontrib.jquery', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix of source filenames. -source_suffix = '.rst' - -# The encoding of source files. -#source_encoding = 'utf-8-sig' - -# The top level toctree document. -master_doc = 'index' - -# General information about the project. -project = u'Pulp ansible Support' - -# Set copyright to current year -copyright = u'2012-{0}, Pulp Team'.format(date.today().year) - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = "0.23.0.dev" -# The full version, including alpha/beta/rc tags. -release = "0.23.0.dev" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -#language = None - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build', 'pulpdocs'] - -# The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] - -# Set autodoc default options -# Document all module/class/etc members, even if they have no docstring. -# Show class inheritance, and group class members together by type (attr, method, etc) -autodoc_default_flags = ['members', 'undoc-members'] -autodoc_member_order = 'groupwise' -autoclass_content = 'both' - -# -- Options for HTML output --------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'sphinx_rtd_theme' if sphinx_rtd_theme else 'default' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] if sphinx_rtd_theme else [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -html_additional_pages = {'restapi': 'restapi.html'} - -# If false, no module index is generated. -#html_domain_indices = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'PulpDocs' - - -# -- Options for LaTeX output -------------------------------------------------- - -latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', -} - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_domain_indices = True - -# If true, show URL addresses after external links. -#man_show_urls = False - -# Documents to append as an appendix to all manuals. -#texinfo_appendices = [] - -# If false, no module index is generated. -#texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' - -extlinks = { - 'github': ('https://github.com/pulp/pulpcore/issues/%s', '#%s'), - 'redmine': ('https://pulp.plan.io/issues/%s', '#%s'), -} - -# napoleon uses .. attribute by default, but :ivar: is more succinct and looks better, -# particularly on classes with a lot of attributes, like django models and related objects -napoleon_use_ivar = True - -# set primary domain to python so we don't have to include :py: in xref links -default_domain = 'py' - -from sphinx.domains.python import PythonDomain - -# Adapted from: -# https://github.com/sphinx-doc/sphinx/issues/3866#issuecomment-366014346 -# Required because pulpcore.app and pulpcore.plugin have the same class names -# and Sphinx can't figure out which it should be using. This code defaults to -# pulpcore.app -class MyPythonDomain(PythonDomain): - def find_obj(self, env, modname, classname, name, type, searchmode=0): - """Ensures an object always resolves to the desired module if defined there.""" - orig_matches = PythonDomain.find_obj(self, env, modname, classname, name, type, searchmode) - matches = [] - for match in orig_matches: - match_name = match[0] - desired_name = "pulpcore.app.models." + name.strip('.') - if match_name == desired_name: - matches.append(match) - break - if matches: - return matches - else: - return orig_matches - - -def setup(sphinx): - """Use MyPythonDomain in place of PythonDomain""" - sphinx.add_domain(MyPythonDomain, override=True) - -rst_prolog = """.. attention:: - This documentation will be deactivated in the near future. `Learn More `_ - or go to the `New Pulp Docs `_ (beta). -""" diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index e582053ea..000000000 --- a/docs/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CONTRIBUTING.rst diff --git a/staging_docs/admin/tutorials/.gitkeep b/docs/dev/guides/.gitkeep similarity index 100% rename from staging_docs/admin/tutorials/.gitkeep rename to docs/dev/guides/.gitkeep diff --git a/staging_docs/dev/guides/.gitkeep b/docs/dev/learn/.gitkeep similarity index 100% rename from staging_docs/dev/guides/.gitkeep rename to docs/dev/learn/.gitkeep diff --git a/staging_docs/dev/learn/.gitkeep b/docs/dev/reference/.gitkeep similarity index 100% rename from staging_docs/dev/learn/.gitkeep rename to docs/dev/reference/.gitkeep diff --git a/staging_docs/dev/reference/testing.md b/docs/dev/reference/testing.md similarity index 100% rename from staging_docs/dev/reference/testing.md rename to docs/dev/reference/testing.md diff --git a/staging_docs/dev/reference/.gitkeep b/docs/dev/tutorials/.gitkeep similarity index 100% rename from staging_docs/dev/reference/.gitkeep rename to docs/dev/tutorials/.gitkeep diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index fbcd89b76..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,41 +0,0 @@ -Welcome to Pulp Ansible's documentation! -======================================== - -Use ``pulp_ansible`` to create a private Galaxy. It doesn't have a UI currently, but using an API -you can: - -* Mirror a subset of roles on-premise -* Mirror all of Galaxy’s roles on-premise -* Store private Ansible roles on-premise -* Install Roles from pulp_ansible using the `ansible-galaxy` CLI -* Version Role content over time and rollback if necessary -* Support for the new multi-role content type from Galaxy - -Issues are tracked `in Github `_. You can file -a new issue or feature request `here `_. -You can also ask questions in the #pulp-ansible channel on -`Matrix `_. - - -Table of Contents ------------------ - -.. toctree:: - :maxdepth: 1 - - installation - workflows/index - restapi - bindings - settings - contributing - testing - changes - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index bca57df93..000000000 --- a/docs/installation.rst +++ /dev/null @@ -1,133 +0,0 @@ -Installation -============ - -Install using Ansible ---------------------- - -pulpcore provides an `Ansible Installer `_ that can be used to -install ``pulp_ansible``. For example if your host is in your Ansible inventory as ``myhost`` you -can install onto it with: - -.. code-block:: bash - - ansible-galaxy install geerlingguy.postgresql - ansible-galaxy collection install pulp.pulp_installer - -Create your pulp_ansible.yml playbook to use with the installer: - -.. code-block:: yaml - - --- - - hosts: all - vars: - pulp_settings: - secret_key: << YOUR SECRET HERE >> - content_origin: "http://{{ ansible_fqdn }}" - pulp_default_admin_password: << YOUR PASSWORD HERE >> - pulp_install_plugins: - pulp-ansible: {} - roles: - - role: pulp.pulp_installer.pulp_all_services - environment: - DJANGO_SETTINGS_MODULE: pulpcore.app.settings - -Then install it onto ``myhost`` with: - -.. code-block:: bash - - ansible-playbook pulp_ansible.yml -l myhost - - -Install with pulplift ---------------------- - -`pulplift `_ combines the Ansible installer above with `Vagrant -`_ to easily try ``pulp_ansible`` on a local VM. - -First you'll need to `install Vagrant `_. - -.. code-block:: bash - - git clone --recurse-submodules https://github.com/pulp/pulplift.git - cd pulplift - -Configure pulplift to install ``pulp_ansible``: - -.. code-block:: bash - - cat > local.user-config.yml <`_ - - -Install ``pulp_ansible`` from source ------------------------------------- - -.. code-block:: bash - - git clone https://github.com/pulp/pulp_ansible.git - cd pulp_ansible - python setup.py develop - -After installing the code, configure Pulp to connect to Redis and PostgreSQL with the `pulpcore -configuration instructions `_ - - -Run Migrations --------------- - -.. code-block:: bash - - django-admin migrate ansible - - -Run Services ------------- - -.. code-block:: bash - - django-admin runserver 24817 - gunicorn pulpcore.content:server --bind 'localhost:24816' --worker-class 'aiohttp.GunicornWebWorker' -w 2 - sudo systemctl restart pulpcore-resource-manager - sudo systemctl restart pulpcore-worker@1 - - -Checking your Installation --------------------------- - -The Status API is a good way to check your installation. Here's an example using httpie in a Fedora -environment:: - - sudo yum install httpie -y - http :80/pulp/api/v3/status/ diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 71bcdb9a5..000000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR=_build -set SPHINXPROJ=PulpAnsible - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/restapi.rst b/docs/restapi.rst deleted file mode 100644 index 252c3b3be..000000000 --- a/docs/restapi.rst +++ /dev/null @@ -1,9 +0,0 @@ -REST API -======== - -Pulpcore Reference: `pulpcore API documentation `_. - -Pulp Ansible API ----------------- - -See the `pulp_ansible API documentation <../restapi.html>`_ diff --git a/docs/settings.rst b/docs/settings.rst deleted file mode 100644 index 389da1509..000000000 --- a/docs/settings.rst +++ /dev/null @@ -1,94 +0,0 @@ -Settings -======== - -`pulp_ansible` provides a few settings to control various features. These settings are settable -with dynaconf in various as a regular Pulp setting. See the `pulpcore Setting `_. - - -ANSIBLE_API_HOSTNAME -^^^^^^^^^^^^^^^^^^^^ - The origin, e.g. "http://example.com" that will instruct the client how to find the Pulp API - service. This URL is formed in various Galaxy APIs (V1, V2, V3) responses. - - This defaults to http on your fqdn, which is usable with the Ansible installer's default Nginx - configuration. So if `example.com` is your fqdn, this would default to "http://example.com". - - -ANSIBLE_CONTENT_HOSTNAME -^^^^^^^^^^^^^^^^^^^^^^^^ - - The origin, e.g. "http://example.com" that will instruct the client how to find the Pulp content - app. This URL is formed in various Galaxy APIs (V1, V2, V3) responses. - - This defaults to `CONTENT_ORIGIN `_. - By default it includes the ``pulp/content`` subpath. So if `https://example.com` is your - CONTENT_ORIGIN, this would default to "https://example.com/pulp/content". - - -ANSIBLE_SIGNATURE_REQUIRE_VERIFICATION -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - By default, ``pulp_ansible`` rejects uploaded signatures if they cannot be verified against a - public key specified on the repository. Setting this to false will allow accepting signatures - if no key was specified. A repository with a configured key will always reject invalid - signatures. - - -ANSIBLE_SIGNING_TASK_LIMITER -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - This number determines the amount of concurrent signing processes that can be spawned at one time - during a signature task. Increasing this number will generally increase the speed of the task, but - will also consume more resources of the worker. Defaults to 10 concurrent processes. - - -GALAXY_API_ROOT -^^^^^^^^^^^^^^^ - - By default the Galaxy V1, V2, and V3 APIs are rooted at - "/pulp_ansible/galaxy//api/", but this is configurable. Specifying `GALAXY_API_ROOT` - will re-root the Galaxy API to a different URL namespace. - - The `` must be included, which corresponds to the `base_path` of an - `Ansible Distribution`. Clients using the Galaxy API will only receive content served by that - `Ansible Distribution`. - - -ANSIBLE_DEFAULT_DISTRIBUTION_PATH -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Set the distribution base path to be used on the ``GALAXY_API_ROOT/default/api/`` endpoint. - By default, this is set to ``None``, which causes the API to return a 404 on the ``default`` - endpoint. - - -ANSIBLE_URL_NAMESPACE -^^^^^^^^^^^^^^^^^^^^^ - - The Django URL namespace to be used when generating URLs that are returned by the galaxy - APIs. Setting this allows for the Galaxy APIs to redirect requests to django URLs in other apps. - This defaults to the pulp ansible URL router. - - -ANSIBLE_COLLECT_DOWNLOAD_LOG -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - A flag to activate collecting download logs about collections consumed. You can dump the - collected information using ``pulpcore-manager download-log``. - - -ANSIBLE_AUTHENTICATION_CLASSES -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - A list of authentication classes to be used to authenticate requests to the Galaxy API. Defaults - to ``REST_FRAMEWORK__DEFAULT_AUTHENTICATION_CLASSES``. See `authentication docs - `_ for more. - - -ANSIBLE_PERMISSION_CLASSES -^^^^^^^^^^^^^^^^^^^^^^^^^^ - - A list of permission classes to be used to authorize requests to the Galaxy API. Defaults to - ``REST_FRAMEWORK__DEFAULT_PERMISSION_CLASSES``. See `authorization docs - `_ for more. \ No newline at end of file diff --git a/docs/template_gitref b/docs/template_gitref deleted file mode 100644 index 3d9674dcd..000000000 --- a/docs/template_gitref +++ /dev/null @@ -1 +0,0 @@ -2021.08.26-361-gcd6f9f0 diff --git a/docs/testing.rst b/docs/testing.rst deleted file mode 100644 index 7a9b249b4..000000000 --- a/docs/testing.rst +++ /dev/null @@ -1,47 +0,0 @@ -Testing -======= - -Integration with the ``ansible-galaxy`` ---------------------------------------- - -These are all contained in the ``pulp_ansible.tests.functional.cli`` package. The following -workflows have tests: - -* ``ansible-galaxy collection install`` - the installation of collection content is tested by - ``pulp_ansible.tests.functional.cli.test_collection_install`` - -* ``ansible-galaxy collection publish`` - this uploading of a collection to Pulp is tested by - ``pulp_ansible.tests.functional.cli.test_collection_upload`` - -* ``ansible-galaxy role install`` - the installation of role content is tested by - ``pulp_ansible.tests.functional.cli.test_role_install`` - - -Galaxy APIs ------------ - -The Galaxy V2 and V3 APIs have tests. - -* ``pulp_ansible.tests.functional.api.collection.v2`` - The V2 collection API - -* ``pulp_ansible.tests.functional.api.collection.v3`` - The V3 collection API - -* ``pulp_ansible.tests.functional.api.role`` - The V2 roles API - - -Scale Testing Tools -------------------- - -These tools are contained in ``pulp_ansible.tests.performance`` and are standalone python utilities -to be called and passed arguments (they use argparse). Here are the tools: - -* ``generate_collections.py`` which generates collections in parallel with Pulp workers. - -* ``fast_load_collections.py`` which loads collections in parallel from a filesystem with Pulp - workers. - -* ``create_repos_with_collections.py`` which creates repositories and repository versions containing - CollectionVersions already in Pulp. - -* ``promote.py`` will select a content unit randomly and add it to N randomly selected - AnsibleRepository objects. This is designed to benchmark adding new content to many repositories. diff --git a/staging_docs/dev/tutorials/.gitkeep b/docs/user/guides/.gitkeep similarity index 100% rename from staging_docs/dev/tutorials/.gitkeep rename to docs/user/guides/.gitkeep diff --git a/staging_docs/user/guides/collections.md b/docs/user/guides/collections.md similarity index 100% rename from staging_docs/user/guides/collections.md rename to docs/user/guides/collections.md diff --git a/staging_docs/user/guides/copy.md b/docs/user/guides/copy.md similarity index 100% rename from staging_docs/user/guides/copy.md rename to docs/user/guides/copy.md diff --git a/staging_docs/user/guides/roles.md b/docs/user/guides/roles.md similarity index 100% rename from staging_docs/user/guides/roles.md rename to docs/user/guides/roles.md diff --git a/staging_docs/user/guides/signature.md b/docs/user/guides/signature.md similarity index 100% rename from staging_docs/user/guides/signature.md rename to docs/user/guides/signature.md diff --git a/staging_docs/user/index.md b/docs/user/index.md similarity index 100% rename from staging_docs/user/index.md rename to docs/user/index.md diff --git a/staging_docs/user/guides/.gitkeep b/docs/user/learn/.gitkeep similarity index 100% rename from staging_docs/user/guides/.gitkeep rename to docs/user/learn/.gitkeep diff --git a/staging_docs/user/learn/.gitkeep b/docs/user/reference/.gitkeep similarity index 100% rename from staging_docs/user/learn/.gitkeep rename to docs/user/reference/.gitkeep diff --git a/staging_docs/user/reference/.gitkeep b/docs/user/tutorials/.gitkeep similarity index 100% rename from staging_docs/user/reference/.gitkeep rename to docs/user/tutorials/.gitkeep diff --git a/docs/workflows/collections.rst b/docs/workflows/collections.rst deleted file mode 100644 index b30f88235..000000000 --- a/docs/workflows/collections.rst +++ /dev/null @@ -1,309 +0,0 @@ -Collection Workflows -==================== - -Pulp organizes role content into repositories, and you associate the ``ansible-galaxy`` client with -one or more repositories. From a high level you can: - -1. :ref:`Create a repo ` - -2. :ref:`Create a distribution ` expose that repository at a URL - -3. :ref:`Sync content from galaxy.ansible.com ` - -4. :ref:`Install content from the repo with ansible-galaxy ` - - -Pulp-CLI Setup ----------------- - -To use the example commands on this page, install the Pulp-CLI as shown below. - -.. literalinclude:: ../_scripts/setup.sh - :language: bash - - -.. _create-a-collection-repository: - -Create a Repository -------------------- - -Create a repository and name it the ``foo`` repository. - -.. literalinclude:: ../_scripts/repo.sh - :language: bash - -Repository create output:: - - { - "pulp_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/", - "pulp_created": "2021-01-26T22:48:11.479496Z", - "versions_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/", - "latest_version_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/0/", - "name": "foo", - "description": null, - "remote": null - } - -Reference (pulpcore): `Repository API Usage `_ - - - -.. _create-distribution-for-collection: - -Create a Distribution for Repository 'foo' ------------------------------------------- - -This will make the latest Repository Version content available for ``ansible-galaxy` clients. Each -distribution names the url it can be accessed from on an attribute called ``client_url``. The -``client_url`` can be used with the ``ansible-galaxy`` client with the ``-s`` option. See the -:ref:`ansible-galaxy-roles-cli` docs for more details. - -For example a distribution with ``base_path`` set to ``my_content`` could have a URL like:: - - http://pulp.example.com/pulp_ansible/galaxy/my_content/ - - -.. literalinclude:: ../_scripts/distribution_repo.sh - :language: bash - -Distribution create output:: - - Started background task /pulp/api/v3/tasks/48d187f6-d1d0-4d83-b803-dae9fe976da9/ - .Done. - { - "pulp_href": "/pulp/api/v3/distributions/ansible/ansible/148ce745-3dd5-4dda-a0ba-f9c5ec7119e1/", - "pulp_created": "2021-01-26T22:51:34.380612Z", - "base_path": "my_content", - "content_guard": null, - "name": "baz", - "repository": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/", - "repository_version": null, - "client_url": "http://pulp3-source-fedora31.localhost.example.com/pulp_ansible/galaxy/my_content/" - } - -Create a Distribution for a RepositoryVersion (optional) --------------------------------------------------------- - -Instead of always distributing the latest RepositoryVersion, you can also specify a specific -RepositoryVersion for a Distribution. This should be used in place of the distribution above, not in -addition to it. - -.. literalinclude:: ../_scripts/distribution_repo_version.sh - :language: bash - -Distribution create output:: - - Started background task /pulp/api/v3/tasks/48d187f6-d1d0-4d83-b803-dae9fe976da9/ - .Done. - { - "pulp_href": "/pulp/api/v3/distributions/ansible/ansible/148ce745-3dd5-4dda-a0ba-f9c5ec7119e1/", - "pulp_created": "2021-01-26T22:51:34.380612Z", - "base_path": "my_content", - "content_guard": null, - "name": "baz", - "repository": null, - "repository_version": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/", - "client_url": "http://pulp3-source-fedora31.localhost.example.com/pulp_ansible/galaxy/my_content/" - } - -.. _create-collection-remote: - -Create a CollectionRemote -------------------------- - -Creating a CollectionRemote object allows Pulp to sync Collections from an external -content source. This is most commonly is ``https://galaxy.ansible.com/`` or another ``pulp_ansible`` -instance. - -In this example we will be syncing the Collection with ``namespace=testing`` and ``name=ansible_testing_content`` -from ``https://galaxy-dev.ansible.com/``. - -.. literalinclude:: ../_scripts/remote-collection.sh - :language: bash - -Remote create output:: - - { - "pulp_href": "/pulp/api/v3/remotes/ansible/collection/80ba27e3-b4d6-4ddb-9677-9e40c04352ef/", - "pulp_created": "2021-01-26T23:16:06.790367Z", - "name": "cbar", - "url": "https://galaxy-dev.ansible.com/", - "ca_cert": null, - "client_cert": null, - "client_key": null, - "tls_validation": true, - "proxy_url": null, - "username": null, - "password": null, - "pulp_last_updated": "2021-01-26T23:16:06.790390Z", - "download_concurrency": 10, - "policy": "immediate", - "total_timeout": null, - "connect_timeout": null, - "sock_connect_timeout": null, - "sock_read_timeout": null, - "requirements_file": "collections:\n - testing.ansible_testing_content", - "auth_url": null, - "token": null, - "rate_limit": null - } - -For `remote sources that require authentication `_, tokens can be used. You can provide the ``token`` -and/or ``auth_url``. - -In this example we will be syncing the Collection with ``namespace=testing`` and ``name=ansible_testing_content`` -from ``https://cloud.redhat.com/api/automation-hub/v3/collections/testing/ansible_testing_content``. - -.. literalinclude:: ../_scripts/remote-collection-token.sh - :language: bash - -Remote create output:: - - { - "pulp_href": "/pulp/api/v3/remotes/ansible/collection/80ba27e3-b4d6-4ddb-9677-9e40c04352ef/", - "pulp_created": "2021-01-26T23:16:06.790367Z", - "name": "abar", - "url": "https://cloud.redhat.com/api/automation-hub/", - "ca_cert": null, - "client_cert": null, - "client_key": null, - "tls_validation": false, - "proxy_url": null, - "username": null, - "password": null, - "pulp_last_updated": "2021-01-26T23:16:06.790390Z", - "download_concurrency": 10, - "policy": "immediate", - "total_timeout": null, - "connect_timeout": null, - "sock_connect_timeout": null, - "sock_read_timeout": null, - "requirements_file": "collections:\n - testing.ansible_testing_content", - "auth_url": "https://sso.qa.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token", - "token": "$ANSIBLE_TOKEN_AUTH", - "rate_limit": null - } - -Sync Repository foo with CollectionRemote ------------------------------------------ - -Use the CollectionRemote object to kick off a synchronize task by specifying the Repository to -sync with. You are telling Pulp to fetch Collection content from the external source. - -.. literalinclude:: ../_scripts/sync-collection.sh - :language: bash - -Repository Version GET Response (when complete):: - - - { - "pulp_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/", - "pulp_created": "2021-01-26T23:25:06.473972Z", - "number": 1, - "base_version": null, - "content_summary": { - "added": { - "ansible.collection_version": { - "count": 2, - "href": "/pulp/api/v3/content/ansible/collection_versions/?repository_version_added=/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/" - } - }, - "removed": {}, - "present": { - "ansible.collection_version": { - "count": 2, - "href": "/pulp/api/v3/content/ansible/collection_versions/?repository_version=/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/" - } - } - } - } - - - -.. _ansible-galaxy-collections-cli: - -Install a Collection, hosted by Pulp, using ``ansible-galaxy`` --------------------------------------------------------------- - -You can use `ansible-galaxy` to install a collection by its namespace and name from pulp_ansible -using the `install` command. For example to install the `hello` collection from above into a -directory `~/collections` you can specify: - -``ansible-galaxy collection install testing.ansible_testing_content -c -s http://localhost/pulp_ansible/galaxy/my_content/`` - - -This assumes that the `hello` Collection is being served by the Distribution `ansible-galaxy` is -configured to use. - -Using a specific version -~~~~~~~~~~~~~~~~~~~~~~~~ - -Install your collection by name by specifying the distribution serving your Repository's content using the -``-s`` option. - -``ansible-galaxy collection install testing.ansible_testing_content:4.0.6 -c -s http://localhost/pulp_ansible/galaxy/my_content/`` - -Note: the ``-c`` flag tells ``ansible-galaxy`` to ignore self signed https certificates. - -Configuring ansible-galaxy -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use the `ansible-galaxy config files `_ to specify the distribution -``ansible-galaxy`` should interact with. To use this, set up your distribution in your ansible -config (e.g. ``~/.ansible.cfg`` or ``/etc/ansible/ansible.cfg``): - -.. code:: - - [galaxy] - server_list = pulp, my_fallback_server - - [galaxy_server.pulp] - url = http://localhost/pulp_ansible/galaxy/my_content/ - - [galaxy_server.my_fallback_server] - url = http://localhost/pulp_ansible/galaxy/my_other_content/ - username = my_user - password = my_password - - [galaxy_server.deprecated] - url = http://localhost/pulp_ansible/galaxy/deprecated/ - username = my_user - password = my_password - -Servers will be used in the order that they appear in ``server_list`` in the configuration file. Specific servers -can also be specified using the ``-s`` (or ``--server``) flag, either by their name or URL. In this example -``ansible-galaxy`` will attempt to fetch content from ``pulp`` and fallback to ``my_fallback_server`` if it can't -find anything. The ``deprecated`` server is not listed under ``server_list``, so ``ansible-galaxy`` won't pull -content from it unless the server is specified explicitly with the ``-s`` flag. - -.. code:: - - # Downloads from the "pulp" server - ansible-galaxy collection install testing.ansible_testing_content:4.0.6 - - # Downloads from the "deprecated" server - ansible-galaxy collection install testing.ansible_testing_content:4.0.6 -s deprecated - - -.. _collection-publish: - -Publish (Upload) a Collection ------------------------------ - -You can use `ansible-galaxy` to publish any `built artifact `_ to pulp_ansible by running:: - - ansible-galaxy collection build # from inside the root directory of the collection - ansible-galaxy collection publish path/to/artifact.tar.gz - -For example if you have ansible-galaxy installed and configured the script below will upload a -Collection to pulp_ansible and display it:: - - ansible-galaxy collection init namespace_name.collection_name - ansible-galaxy collection build namespace_name/collection_name/ - ansible-galaxy collection publish namespace_name-collection_name-1.0.0.tar.gz -c - -The client upload the Collection to the Repository associated with the Distribution. Each upload -creates a new Repository Version for the Repository. diff --git a/docs/workflows/copy.rst b/docs/workflows/copy.rst deleted file mode 100644 index e1c07e80c..000000000 --- a/docs/workflows/copy.rst +++ /dev/null @@ -1,201 +0,0 @@ -Copy Workflows -============== - -If you want to copy Ansible Collections or Roles from one repository into another repository, you -have two options for doing so. - - -.. _basic-modify-workflow: - -Basic Repository Modification API ---------------------------------- - -Like all Pulp repositories, you can use the ${repo_href}/modify/ endpoint to: - -* add or remove individual Collections or Roles from a repository by HREF -* roll back the content present in a repository to that of a previous version using 'base_version' -* clone a repository version using '"base_version". This operation will create a new repository - version in the current repository which is a copy of the one specified as the "base_version", - regardless of what content was previously present in the repository. This can be combined with - adding and removing content units in the same call. - -For example:: - - http POST localhost/pulp/api/v3/repositories/ansible/ansible/05813fa6-cf0b-435b-b54b-5a30fc370848/modify/ \ - add_content_units:="['/pulp/api/v3/content/ansible/collections/d2bab58c-50f2-4f1d-9cf0-8ceb1680f31b/']" - - -.. copy-workflow: - -Advanced Copy Workflow ----------------------- - -Ansible Collections store their ``deprecated`` status data at the Repository Version level, and the -"modify" workflow above does not properly preserve ``deprecated`` because the source of the content -is not known. For this reason a ``copy`` endpoint is available at ``/pulp/api/v3/ansible/copy/`` -which is similar to modify except the source of content, e.g. Collections, is declared which -allows the ``deprecated`` status to follow the content. - -For example say you have two ``AnsibleRepository`` Repositories two ``AnsibleDistribution`` -Distributions exposing their content. One contains Collections with ``deprecate=True`` and the other -has no Collections in it. - -Viewing the Repository with content you can see:: - - http GET http://example.com/pulp_ansible/galaxy/my_content/api/v3/collections/ - - HTTP 200 OK - Allow: GET, HEAD, OPTIONS - Content-Type: application/json - Vary: Accept - - { - "meta": { - "count": 1 - }, - "links": { - "first": "/pulp_ansible/galaxy/my_content/api/v3/collections/?limit=10&offset=0", - "previous": null, - "next": null, - "last": "/pulp_ansible/galaxy/my_content/api/v3/collections/?limit=10&offset=0" - }, - "data": [ - { - "href": "/pulp_ansible/galaxy/my_content/api/v3/collections/testing/k8s_demo_collection/", - "namespace": "testing", - "name": "k8s_demo_collection", - "deprecated": true, - "versions_url": "/pulp_ansible/galaxy/my_content/api/v3/collections/testing/k8s_demo_collection/versions/", - "highest_version": { - "href": "/pulp_ansible/galaxy/my_content/api/v3/collections/testing/k8s_demo_collection/versions/0.0.3/", - "version": "0.0.3" - }, - "created_at": "2020-10-28T19:22:24.577606Z", - "updated_at": "2020-10-28T19:22:24.577606Z" - } - ] - } - -Then viewing the empty repository you can see:: - - http GET http://example.com/pulp_ansible/galaxy/dest_repo/api/v3/collections/ - - HTTP 200 OK - Allow: GET, HEAD, OPTIONS - Content-Type: application/json - Vary: Accept - - { - "meta": { - "count": 0 - }, - "links": { - "first": "/pulp_ansible/galaxy/dest_repo/api/v3/collections/?limit=10&offset=0", - "previous": null, - "next": null, - "last": "/pulp_ansible/galaxy/dest_repo/api/v3/collections/?limit=10&offset=0" - }, - "data": [] - } - - -In this situation if you use the ``modify`` call since it doesn't know which Repository Version to -take the ``deprecated`` data from it isn't preserved For example if you run:: - - http POST http://example.com/pulp/api/v3/repositories/ansible/ansible/05813fa6-cf0b-435b-b54b-5a30fc370848/modify/ \ - add_content_units:="['/pulp/api/v3/content/ansible/collections/d2bab58c-50f2-4f1d-9cf0-8ceb1680f31b/']" - -And you list the dest_repo via the Galaxy V3 API (that the CLI uses) you would see -``deprecated=False``. - -However you could instead use the ``copy`` API as follows: - -.. code-block:: sh - - POST /pulp/api/v3/ansible/copy/ - config:=[ - {"source_repo_version": "$SRC_REPO_VERS_HREF", "dest_repo": "$DEST_REPO_HREF", "content": [$CONTENT_HREF1]} - ] - -Then if you list the contents on the destination repository, you would see the ``deprecated=True`` -was preserved:: - - http GET http://example.com/pulp_ansible/galaxy/dest_repo/api/v3/collections/ - - HTTP 200 OK - Allow: GET, HEAD, OPTIONS - Content-Type: application/json - Vary: Accept - - { - "meta": { - "count": 1 - }, - "links": { - "first": "/pulp_ansible/galaxy/dest_repo/api/v3/collections/?limit=10&offset=0", - "previous": null, - "next": null, - "last": "/pulp_ansible/galaxy/dest_repo/api/v3/collections/?limit=10&offset=0" - }, - "data": [ - { - "href": "/pulp_ansible/galaxy/dest_repo/api/v3/collections/testing/k8s_demo_collection/", - "namespace": "testing", - "name": "k8s_demo_collection", - "deprecated": true, - "versions_url": "/pulp_ansible/galaxy/dest_repo/api/v3/collections/testing/k8s_demo_collection/versions/", - "highest_version": { - "href": "/pulp_ansible/galaxy/dest_repo/api/v3/collections/testing/k8s_demo_collection/versions/0.0.3/", - "version": "0.0.3" - }, - "created_at": "2020-10-28T19:22:24.577606Z", - "updated_at": "2020-10-28T19:22:24.577606Z" - } - ] - } - - -Copy All Content ----------------- - -When calling ``copy`` you can omit the ``content`` argument and ``copy`` will copy all content from -the ``source_repo_version`` to a new Repository Version created on the ``dest_repo``. That would be -similar to: - -.. code-block:: sh - - POST /pulp/api/v3/ansible/copy/ - config:=[ - {"source_repo_version": "$SRC_REPO_VERS_HREF", "dest_repo": "$DEST_REPO_HREF"} - ] - - -Specifying a Destination Base Version -------------------------------------- - -In some situations, you may want the content being copied to be applied not to the latest version -of the ``dest_repo``, and in that case, you can additionally specify the ``dest_base_version`` and -that would be used instead of the latest RepositoryVersion of ``dest_repo``: - -.. code-block:: sh - - POST /pulp/api/v3/ansible/copy/ - config:=[ - {"source_repo_version": "$SRC_REPO_VERS_HREF", "dest_repo": "$DEST_REPO_HREF", "dest_base_version": "$DEST_BASE_VERSION", "content": [$CONTENT_HREF1, $CONTENT_HREF2]} - ] - - -Multi-Repo Copy ---------------- - -You can specify a more complicated ``config`` option which can express multiple copy operations in -one call. Each entry is the dictionary of ``source_repo_version``, ``dest_repo``, and optional -``content``, in a list form. - -.. code-block:: sh - - POST /pulp/api/v3/ansible/copy/ - config:=[ - {"source_repo_version": "$SRC_REPO_VERS_HREF", "dest_repo": "$DEST_REPO_HREF", "content": [$CONTENT_HREF1, $CONTENT_HREF2]}, - {"source_repo_version": "$SRC_REPO_VERS_HREF2", "dest_repo": "$DEST_REPO_HREF2", "content": []}, - ] diff --git a/docs/workflows/index.rst b/docs/workflows/index.rst deleted file mode 100644 index fdf3876b0..000000000 --- a/docs/workflows/index.rst +++ /dev/null @@ -1,28 +0,0 @@ - -.. note:: - - To use these examples you will need to install ``httpie`` to make requests and ``jq`` to parse - responses. ``httpie`` has ``netrc`` support so each request submits Basic Authentication with - it. For Pulp's defaults the ``.netrc`` would have the following configuration: - - .. code-block:: bash - - machine localhost - login admin - password admin - -.. note:: - - To make these workflows copy/paste-able, we make use of environment variables. The first - variable to set is the hostname and port:: - - export BASE_ADDR=http:// - - -.. toctree:: - :maxdepth: 2 - - roles - collections - copy - signature diff --git a/docs/workflows/roles.rst b/docs/workflows/roles.rst deleted file mode 100644 index afafbb531..000000000 --- a/docs/workflows/roles.rst +++ /dev/null @@ -1,219 +0,0 @@ -Role Workflows -============== - -Pulp organizes role content into repositories, and you associate the ``ansible-galaxy`` client with -one or more repositories. From a high level you can: - -1. :ref:`Create a repo ` - -2. :ref:`Create a distribution ` expose that repository at a URL - -3. :ref:`Sync content from galaxy.ansible.com ` - -4. :ref:`Install content from the repo with ansible-galaxy ` - - -Pulp-CLI Setup ----------------- - -To use the example commands on this page, install the Pulp-CLI as shown below. - -.. literalinclude:: ../_scripts/setup.sh - :language: bash - - -.. _create-a-roles-repository: - -Create a Repository -------------------- - -Create a repository and name it the ``foo`` repository. - -.. literalinclude:: ../_scripts/repo.sh - :language: bash - -Repository create output:: - - { - "pulp_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/", - "pulp_created": "2021-01-26T22:48:11.479496Z", - "versions_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/", - "latest_version_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/0/", - "name": "foo", - "description": null, - "remote": null - } - -Reference (pulpcore): `Repository API Usage `_ - - -.. _create-distribution-for-repo: - -Create a Distribution for Repository 'foo' ------------------------------------------- - -This will make the latest Repository Version content available for ``ansible-galaxy`` clients. Each -distribution names the url it can be accessed from on an attribute called ``client_url``. The -``client_url`` can be used with the ``ansible-galaxy`` client with the ``-s`` option. See the -:ref:`ansible-galaxy-roles-cli` docs for more details. - -For example a distribution with ``base_path`` set to ``my_content`` could have a URL like:: - - http://pulp.example.com/pulp_ansible/galaxy/my_content/ - - -.. literalinclude:: ../_scripts/distribution_repo.sh - :language: bash - -Distribution create output:: - - Started background task /pulp/api/v3/tasks/48d187f6-d1d0-4d83-b803-dae9fe976da9/ - .Done. - { - "pulp_href": "/pulp/api/v3/distributions/ansible/ansible/148ce745-3dd5-4dda-a0ba-f9c5ec7119e1/", - "pulp_created": "2021-01-26T22:51:34.380612Z", - "base_path": "my_content", - "content_guard": null, - "name": "baz", - "repository": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/", - "repository_version": null, - "client_url": "http://pulp3-source-fedora31.localhost.example.com/pulp_ansible/galaxy/my_content/" - } - -Create a Distribution for a RepositoryVersion (optional) --------------------------------------------------------- - -Instead of always distributing the latest RepositoryVersion, you can also specify a specific -RepositoryVersion for a Distribution. This should be used in place of the distribution above, not in -addition to it. - -.. literalinclude:: ../_scripts/distribution_repo_version.sh - :language: bash - -Distribution create output:: - - Started background task /pulp/api/v3/tasks/48d187f6-d1d0-4d83-b803-dae9fe976da9/ - .Done. - { - "pulp_href": "/pulp/api/v3/distributions/ansible/ansible/148ce745-3dd5-4dda-a0ba-f9c5ec7119e1/", - "pulp_created": "2021-01-26T22:51:34.380612Z", - "base_path": "my_content", - "content_guard": null, - "name": "baz", - "repository": null, - "repository_version": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/", - "client_url": "http://pulp3-source-fedora31.localhost.example.com/pulp_ansible/galaxy/my_content/" - } - -.. _create-role-remote: - -Create a Remote ---------------- - -Creating a Remote object informs Pulp about an external content source, which most commonly is -``https://galaxy.ansible.com/`` or another ``pulp_ansible`` instance. In this case, we will be -syncing all Roles where ``namespace=elastic`` on Galaxy. You can browse those Roles Pulp will import -`here `_. - -.. literalinclude:: ../_scripts/remote.sh - :language: bash - -Remote create output:: - - { - "pulp_href": "/pulp/api/v3/remotes/ansible/role/38f37de9-842c-4690-a73c-9e813853b28b/", - "pulp_created": "2021-01-26T22:55:17.126745Z", - "name": "bar", - "url": "https://galaxy.ansible.com/api/v1/roles/?owner__username=elastic", - "ca_cert": null, - "client_cert": null, - "client_key": null, - "tls_validation": true, - "proxy_url": null, - "username": null, - "password": null, - "pulp_last_updated": "2021-01-26T22:55:17.126755Z", - "download_concurrency": 10, - "policy": "immediate", - "total_timeout": null, - "connect_timeout": null, - "sock_connect_timeout": null, - "sock_read_timeout": null - } - -.. _role-sync-with-remote: - -Sync Repository foo with Remote -------------------------------- - -Use the Remote object to kick off a synchronize task by specifying the Repository to -sync with. You are telling Pulp to fetch content from the Remote and add to the Repository. - -.. literalinclude:: ../_scripts/sync.sh - :language: bash - -Repository Version show output:: - - { - "pulp_href": "/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/", - "pulp_created": "2021-01-26T22:57:55.451200Z", - "number": 1, - "base_version": null, - "content_summary": { - "added": { - "ansible.role": { - "count": 56, - "href": "/pulp/api/v3/content/ansible/roles/?repository_version_added=/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/" - } - }, - "removed": {}, - "present": { - "ansible.role": { - "count": 56, - "href": "/pulp/api/v3/content/ansible/roles/?repository_version=/pulp/api/v3/repositories/ansible/ansible/b17950e8-cee8-493a-b735-0d04905cf067/versions/1/" - } - } - } - } - -Reference (pulpcore): `Repository Version List API Usage `_ - - -.. _ansible-galaxy-roles-cli: - -Install a Role, hosted by Pulp, using ``ansible-galaxy`` --------------------------------------------------------- - -Using a direct path -~~~~~~~~~~~~~~~~~~~ - -Install your role by name by specifying the distribution serving your Repository's content using the -``-s`` option. - -``ansible-galaxy install elasticsearch,6.2.4 -c -s http://pulp.example.com/pulp_ansible/galaxy/my_content/`` - - -Configuring ansible-galaxy Permanently -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use the `ansible-galaxy config files `_ to specify the distribution ``ansible-galaxy`` should interact -with. To use this, set up your distribution in your ansible config (e.g. ``~/.ansible.cfg`` or -``/etc/ansible/ansible.cfg``): - -.. code:: - - [galaxy] - server: http://pulp.example.com/pulp_ansible/galaxy/my_content/ - -Then you can install without the ``-s`` url - -.. code:: - - $ ansible-galaxy install elastic.elasticsearch,6.2.4 - - downloading role 'elasticsearch', owned by elastic - - downloading role from http://localhost:24816/pulp/content/dev/elastic/elasticsearch/6.2.4.tar.gz - - extracting elastic.elasticsearch to /home/vagrant/.ansible/roles/elastic.elasticsearch - - elastic.elasticsearch (6.2.4) was installed successfully diff --git a/docs/workflows/signature.rst b/docs/workflows/signature.rst deleted file mode 100644 index 6cb4f236f..000000000 --- a/docs/workflows/signature.rst +++ /dev/null @@ -1,109 +0,0 @@ -Signature Workflows -=================== - -``pulp_ansible`` supports Collection signing, syncing, and uploading. Collection signing adds extra -validation when installing Collections with `ansible-galaxy`. Check out the workflows below to see -how to add signature support. - -Setup ------ -In order to verify signature validity on uploads you will need to store your trusted key on the -repositories ``gpgkey`` attribute. - -.. note:: - You can upload signatures without supplying Pulp any key, but ``pulp_ansible`` will not - perform validity checks on the uploaded signature. You will also have to configure the - ``ANSIBLE_SIGNATURE_REQUIRE_VERIFICATION`` setting to ``False``. By default and once a key is - provided, all signatures impossible to verify are rejected. - -In order to have ``pulp_ansible`` sign collections stored in your repositories you will need to set -up a signing service. First, create/import the key you intend to sign your collections with onto -your Pulp system. Second, create a signing script on your Pulp system with the parameters you want -on the generated signatures. Galaxy uses a signing script like the one below: - -.. code-block:: bash - - #!/usr/bin/env bash - FILE_PATH=$1 - SIGNATURE_PATH="$1.asc" - - # Create a detached signature - gpg --quiet --batch --homedir ~/.gnupg/ --detach-sign --local-user "${PULP_SIGNING_KEY_FINGERPRINT}" \ - --armor --output ${SIGNATURE_PATH} ${FILE_PATH} - - # Check the exit status - STATUS=$? - if [[ ${STATUS} -eq 0 ]]; then - echo {\"file\": \"${FILE_PATH}\", \"signature\": \"${SIGNATURE_PATH}\"} - else - exit ${STATUS} - fi - -Third, create the signing service using ``pulpcore-manager``: - -.. code-block:: bash - - pulpcore-manager add-signing-service ansible-signing-service $SCRIPT_LOCATION $PUBKEY_FINGERPRINT - -Reference: `Signing Service `_ - -Signing Collections -------------------- - -Sign collections stored in repository ``foo`` with the signing service ``ansible-signing-service``: - -.. code-block:: bash - - pulp ansible repository sign --name foo --signing-service ansible-signing-service - -By default it will sign everything in the repository, specify ``--content-units`` with a list of -specific collection hrefs you want to sign. Collections can have multiple signatures attached to -them in a repository as long as they are all from different keys. - -Syncing Signed Collections --------------------------- - -Signature information will be present in the Galaxy APIs if your repository has signatures in it -and when syncing from a Galaxy repository, signatures will automatically be synced as well if -present. You can also specify to only sync Collections that have signatures with the -``signed_only`` field on the remote. e.g.: - -.. code-block:: bash - - pulp ansible remote update --name foo --signed-only - # Sync task will only sync collections with signatures now - pulp ansible repository sync --name foo --remote foo - -Uploading Signed Collections ----------------------------- - -Signatures can also be manually created and uploaded to ``pulp_ansible``. - -.. code-block:: bash - - pulp ansible content -t signature upload --file $SIGNATURE --collection $COLLECTION_HREF - -Signatures can be verified upon upload by setting the ``keyring`` field on the repository to your -keyring location, and then specifying the ``repository`` option when uploading the signature. - -.. code-block:: bash - - pulp ansible repository update --name foo --keyring $KEYRING_FILE_LOCATION - # Validate signature against keyring of repository - pulp ansible content -t signature upload --file $SIGNATURE --collection $COLLECTION_HREF --repository foo - -Verifying Signatures with ``ansible-galaxy`` --------------------------------------------- - -Installing collections from ``pulp_ansible`` with signatures via `ansible-galaxy` requires -specifying the keyring to perform the validation upon install: - -.. code-block:: bash - - ansible-galaxy collection install $COLLECTION -s "$BASE_ADDR"pulp_ansible/galaxy/foo/api/ --keyring $KEYRING_FILE_LOCATION - -You can also verify already installed collections with the verify command: - -.. code-block:: bash - - ansible-galaxy collection verify $COLLECTION -s "$BASE_ADDR"pulp_ansible/galaxy/foo/api/ --keyring $KEYRING_FILE_LOCATION diff --git a/staging_docs/user/tutorials/.gitkeep b/staging_docs/user/tutorials/.gitkeep deleted file mode 100644 index e69de29bb..000000000