From 04967a56643bf90843e7dc97b63c7b8dc1d1975a Mon Sep 17 00:00:00 2001 From: Aine Riordan <44700011+ariordan-redhat@users.noreply.github.com> Date: Wed, 24 Nov 2021 10:13:15 -0800 Subject: [PATCH] [Backport][Docs] Docs 2.12 backportapalooza7 (#76298) * Stop using "checksumming" instead of "encrypting" in the docs (#76168) * Hashing is not encrypting All encryption systems have a formal inverse function to decrypt A hash is a one way function without inverse by definition * Update docs/docsite/rst/user_guide/playbooks_filters.rst Co-authored-by: Sandra McCann * ansible-core 2.12 dropped support for galaxy.yaml. (#76179) * apt - remove obsolete documentation (#76243) The lock_timeout feature was recently added to the apt module making this section in the documentation no longer necessary * Documentation for other types in collection `requirements.yml` (#75872) * Docs: Link to valid data types for role parameters (#76276) * Fixed typo in keyword_desc.yml (#76280) The description of 'max_fail_percentage' had a typo. * Restore documentation on M() and R() (#76284) * Undo most of bf9944266c45ed3e9001520e1894bf9a212f49de, add note on where R() does not work. Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com> Co-authored-by: Vicente Jimenez Aguilar Co-authored-by: Sandra McCann Co-authored-by: Felix Fontein Co-authored-by: Sam Doran Co-authored-by: Daniel Goldman Co-authored-by: nkoechling --- .../developing_collections_distributing.rst | 4 ++-- .../developing_modules_documenting.rst | 13 +++++++--- docs/docsite/rst/galaxy/user_guide.rst | 5 ++++ .../installing_collections_file.rst | 24 +++++++++++++++++++ .../installing_multiple_collections.txt | 2 +- .../rst/user_guide/collections_using.rst | 14 +++++++---- .../rst/user_guide/playbooks_filters.rst | 4 ++-- .../rst/user_guide/playbooks_reuse_roles.rst | 2 +- lib/ansible/keyword_desc.yml | 2 +- lib/ansible/modules/apt.py | 14 +---------- 10 files changed, 56 insertions(+), 28 deletions(-) create mode 100644 docs/docsite/rst/shared_snippets/installing_collections_file.rst diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst index 1fa1e158a86..d0406680555 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst @@ -54,7 +54,7 @@ You can create additional namespaces on Ansible Galaxy if you choose. For Red Ha * To create a namespace on Galaxy, see `Galaxy namespaces `_ on the Galaxy docsite for details. * To create a namespace on Red Hat Automation Hub, see the `Ansible Certified Content FAQ `_. -Specify the namespace in the :file:`galaxy.yaml` file for each collection. For more information on the :file:`galaxy.yaml` file, see :ref:`collections_galaxy_meta`. +Specify the namespace in the :file:`galaxy.yml` file for each collection. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`. .. _galaxy_get_token: @@ -124,7 +124,7 @@ Building your collection tarball After configuring one or more distribution servers, build a collection tarball. The collection tarball is the published artifact, the object that you upload and other users download to install your collection. To build a collection tarball: -#. Review the version number in your :file:`galaxy.yaml` file. Each time you publish your collection, it must have a new version number. You cannot make changes to existing versions of your collection on a distribution server. If you try to upload the same collection version more than once, the distribution server returns the error ``Code: conflict.collection_exists``. Collections follow semantic versioning rules. For more information on versions, see :ref:`collection_versions`. For more information on the :file:`galaxy.yaml` file, see :ref:`collections_galaxy_meta`. +#. Review the version number in your :file:`galaxy.yml` file. Each time you publish your collection, it must have a new version number. You cannot make changes to existing versions of your collection on a distribution server. If you try to upload the same collection version more than once, the distribution server returns the error ``Code: conflict.collection_exists``. Collections follow semantic versioning rules. For more information on versions, see :ref:`collection_versions`. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`. #. Run ``ansible-galaxy collection build`` from inside the top-level directory of the collection. For example: .. code-block:: bash diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 2932e4f80b9..f620d352923 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -244,6 +244,8 @@ You can link from your module documentation to other module docs, other resource * ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation. * ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.`` +* ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``. Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details. +* ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``. There are also some macros which do not create links but we use them to display certain types of content in a uniform way: @@ -256,12 +258,17 @@ content in a uniform way: .. note:: - For links between modules and documentation within a collection, you can use either of the options above. Use ``U()`` or ``L()`` with full URLs (not relative links). + Cross-references with ``R()`` currently **do not work** inside option and return value documentations. They do work however in the global description, notes, and ``seealso`` descriptions. .. note:: - - When a collection is not the right granularity, use ``C(..)``: - - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.`` + For links between modules and documentation within a collection, you can use any of the options above. For links outside of your collection, use ``R()`` if available. Otherwise, use ``U()`` or ``L()`` with full URLs (not relative links). For modules, use ``M()`` with the FQCN or ``ansible.builtin`` as shown in the example. If you are creating your own documentation site, you will need to use the `intersphinx extension `_ to convert ``R()`` and ``M()`` to the correct links. + +.. note:: + To refer to a group of modules in a collection, use ``R()``. When a collection is not the right granularity, use ``C(..)``: + + - ``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.`` + - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.`` .. note:: diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst index 6c8c0ef2843..0a22b16564a 100644 --- a/docs/docsite/rst/galaxy/user_guide.rst +++ b/docs/docsite/rst/galaxy/user_guide.rst @@ -83,6 +83,11 @@ Downloading a collection for offline use .. include:: ../shared_snippets/download_tarball_collections.txt +Installing a collection from source files +----------------------------------------- + +.. include:: ../shared_snippets/installing_collections_file.rst + Installing a collection from a git repository --------------------------------------------- diff --git a/docs/docsite/rst/shared_snippets/installing_collections_file.rst b/docs/docsite/rst/shared_snippets/installing_collections_file.rst new file mode 100644 index 00000000000..60eccab4312 --- /dev/null +++ b/docs/docsite/rst/shared_snippets/installing_collections_file.rst @@ -0,0 +1,24 @@ +Ansible can also install from a source directory in several ways: + +.. code-block:: yaml + + collections: + # directory containing the collection + - source: ./my_namespace/my_collection/ + type: dir + + # directory containing a namespace, with collections as subdirectories + - source: ./my_namespace/ + type: subdirs + +Ansible can also install a collection collected with ``ansible-galaxy collection build`` or downloaded from Galaxy for offline use by specifying the output file directly: + +.. code-block:: yaml + + collections: + - source: /tmp/my_namespace-my_collection-1.0.0.tar.gz + type: file + +.. note:: + + Relative paths are calculated from the current working directory (where you are invoking ``ansible-galaxy install -r`` from). They are not taken relative to the ``requirements.yml`` file. \ No newline at end of file diff --git a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt index a1bf0265f6a..db49aa922f3 100644 --- a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt +++ b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt @@ -22,7 +22,7 @@ You can specify four keys for each collection entry: The ``version`` key uses the same range identifier format documented in :ref:`collections_older_version`. -The ``type`` key can be set to ``galaxy``, ``url``, ``file``, and ``git``. If ``type`` is omitted, the ``name`` key is used to implicitly determine the source of the collection. +The ``type`` key can be set to ``file``, ``galaxy``, ``git``, ``url``, ``dir``, or ``subdirs``. If ``type`` is omitted, the ``name`` key is used to implicitly determine the source of the collection. When you install a collection with ``type: git``, the ``version`` key can refer to a branch or to a `git commit-ish `_ object (commit or tag). For example: diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst index c0450501146..c6719b46797 100644 --- a/docs/docsite/rst/user_guide/collections_using.rst +++ b/docs/docsite/rst/user_guide/collections_using.rst @@ -37,11 +37,6 @@ Installing an older version of a collection .. include:: ../shared_snippets/installing_older_collection.txt -Installing a collection from a git repository ---------------------------------------------- - -.. include:: ../shared_snippets/installing_collections_git_repo.txt - .. _collection_requirements_file: Install multiple collections with a requirements file @@ -56,6 +51,15 @@ Downloading a collection for offline use .. include:: ../shared_snippets/download_tarball_collections.txt +Installing a collection from source files +----------------------------------------- + +.. include:: ../shared_snippets/installing_collections_file.rst + +Installing a collection from a git repository +--------------------------------------------- + +.. include:: ../shared_snippets/installing_collections_git_repo.txt .. _galaxy_server_config: diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index 9116172beae..80961d46e41 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -1294,8 +1294,8 @@ This allows for dynamic generation of VLAN lists on a Cisco IOS tagged interface .. _hash_filters: -Encrypting and checksumming strings and passwords -================================================= +Hashing and encrypting strings and passwords +============================================== .. versionadded:: 1.9 diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst index 2422830bab1..bc74b210638 100644 --- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst +++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst @@ -320,7 +320,7 @@ role ``meta/argument_specs.yml`` file. All fields are lower-case. :type: - * The data type of the option. Default is ``str``. + * The data type of the option. See :ref:`Argument spec ` for allowed values for ``type``. Default is ``str``. * If an option is of type ``list``, ``elements`` should be specified. :required: diff --git a/lib/ansible/keyword_desc.yml b/lib/ansible/keyword_desc.yml index f0e076c5bc5..1e8d844a3d4 100644 --- a/lib/ansible/keyword_desc.yml +++ b/lib/ansible/keyword_desc.yml @@ -41,7 +41,7 @@ ignore_errors: Boolean that allows you to ignore task failures and continue with ignore_unreachable: Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see :term:`ignore_errors`) but is useful for groups of volatile/ephemeral hosts. loop: "Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)" loop_control: Several keys here allow you to modify/set loop behaviour in a task. See :ref:`loop_control`. -max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. This only wokrs on linear or linear derived strategies. +max_fail_percentage: can be used to abort the run after a given percentage of hosts in the current batch has failed. This only works on linear or linear derived strategies. module_defaults: Specifies default parameter values for modules. name: "Identifier. Can be used for documentation, or in tasks/handlers." no_log: Boolean that controls information disclosure. diff --git a/lib/ansible/modules/apt.py b/lib/ansible/modules/apt.py index 5a00a214017..94baf65d666 100644 --- a/lib/ansible/modules/apt.py +++ b/lib/ansible/modules/apt.py @@ -170,7 +170,7 @@ options: version_added: "2.4" lock_timeout: description: - - How many seconds will this action wait to aquire a lock on the apt db. + - How many seconds will this action wait to acquire a lock on the apt db. - Sometimes there is a transitory lock and this will retry at least until timeout is hit. type: int default: 60 @@ -298,18 +298,6 @@ EXAMPLES = ''' - name: Remove dependencies that are no longer required apt: autoremove: yes - -# Sometimes apt tasks fail because apt is locked by an autoupdate or by a race condition on a thread. -# To check for a lock file before executing, and keep trying until the lock file is released: -- name: Install packages only when the apt process is not locked - apt: - name: foo - state: present - register: apt_action - retries: 100 - until: apt_action is success or ('Failed to lock apt for exclusive operation' not in apt_action.msg and '/var/lib/dpkg/lock' not in apt_action.msg) - - ''' RETURN = '''