From 29ddca2734ccca4d067689055e936b2e30434c41 Mon Sep 17 00:00:00 2001 From: Dmitriy Rabotyagov Date: Thu, 23 Jun 2022 12:16:24 +0200 Subject: [PATCH] Update documentation about installation methods config_template historically was published on PyPi during times before collections were a thing. This was one of the installations methods that is not relevant or preffered since collections are here. That patch aims to update documentation about ways of plugin installation as well as adding deprecation notice of PyPi. In the futher releases we will drop publishing on PyPi. Change-Id: Ie1cd7b305b4d82fd0fbf4568ef20ff3d0236c049 --- README.rst | 25 ++++++++++---- doc/source/index.rst | 34 ++++++++++--------- examples/ansible-role-requirements.yml | 8 ++--- .../pypi_deprecation-93d9628dcdd76f93.yaml | 6 ++++ 4 files changed, 46 insertions(+), 27 deletions(-) create mode 100644 releasenotes/notes/pypi_deprecation-93d9628dcdd76f93.yaml diff --git a/README.rst b/README.rst index 2439417..8bf5aba 100644 --- a/README.rst +++ b/README.rst @@ -7,14 +7,25 @@ Team and repository tags .. Change things from this point on -========================= -OpenStack-Ansible plugins -========================= +================================= +OpenStack-Ansible config_template +================================= -These are the plugins the OpenStack-Ansible deployment project relies on. The -plugins can be added to any Ansible project by simply cloning this repository -and setting up the ``ansible.cfg`` file to point at them as additional plugins -for your project. +This module is an ansible plugin that extends regular template functionality +with the ability to override items in config, in transit, through the use +of a simple dictionary without having to write out various temp files on target +machines. + +WARNING +~~~~~~~ + +Installation from PyPI or as a Python module is deprecated and will be removed +in future releases. +Please, use ansible-galaxy to install the collection. + +================================== +More infromation about the project +================================== Documentation for the project can be found at: https://docs.openstack.org/ansible-config_template/latest/ diff --git a/doc/source/index.rst b/doc/source/index.rst index 12b6dfc..77b2b79 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,6 +1,6 @@ -====================== -Config Template plugin -====================== +========================== +Config Template collection +========================== Synopsis -------- @@ -20,7 +20,7 @@ Examples Example for .conf ^^^^^^^^^^^^^^^^^ -The `config_template` plugin has a variety of tools available. A .conf file +The `config_template` collection has a variety of tools available. A .conf file may include options that are not normally supported in an INI file, but are used in OpenStack, like ListOpt and MultiStrOpt. @@ -146,26 +146,28 @@ Resulting file on the remote host: [hello] cruel = world -Loading -------- +Installing collection +--------------------- -To use the plugin, include this role in your meta/main.yml dependencies +To use the collection, include this in your meta/main.yml: .. code-block :: yaml - dependencies: - - role: ansible-config_template + collections: + - openstack.config_template -Alternatively, move the role to the appropriate plugin folder location -of your ansible configuration. -Example role requirement overload for automatic plugin download ---------------------------------------------------------------- -The Ansible role requirement file can be used to overload the -``ansible-galaxy`` command to automatically fetch the plugins for +Also the Ansible requirement file can be used with the +``ansible-galaxy`` command to automatically fetch the collections for you in a given project. To do this add the following lines to your -``ansible-role-requirements.yml`` file. +``requirements.yml`` file. .. literalinclude:: ../../examples/ansible-role-requirements.yml :language: yaml + +After that simple run the following command to get requirements installed: + + .. code-block :: shell + + $ ansible-galaxy install -r requirements.yml diff --git a/examples/ansible-role-requirements.yml b/examples/ansible-role-requirements.yml index 57f16fa..1195415 100644 --- a/examples/ansible-role-requirements.yml +++ b/examples/ansible-role-requirements.yml @@ -1,4 +1,4 @@ -- name: ansible-config_template - src: https://opendev.org/openstack/ansible-config_template - scm: git - version: master +collections: + - name: https://opendev.org/openstack/ansible-config_template + version: master + type: git diff --git a/releasenotes/notes/pypi_deprecation-93d9628dcdd76f93.yaml b/releasenotes/notes/pypi_deprecation-93d9628dcdd76f93.yaml new file mode 100644 index 0000000..a2ead1c --- /dev/null +++ b/releasenotes/notes/pypi_deprecation-93d9628dcdd76f93.yaml @@ -0,0 +1,6 @@ +--- +deprecations: + - | + Installation from PyPI or as a Python module is deprecated and will be removed + in future releases. + Please, use ``ansible-galaxy`` for plugin installation.