From be2bd2f1af0b4fcd131e18e3df321fd9ddef2fe5 Mon Sep 17 00:00:00 2001 From: Daniel Goldman Date: Tue, 9 Nov 2021 15:18:51 -0500 Subject: [PATCH] Documentation for other types in collection `requirements.yml` (#75872) --- 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 +++++++---- 4 files changed, 39 insertions(+), 6 deletions(-) create mode 100644 docs/docsite/rst/shared_snippets/installing_collections_file.rst 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: