Clarify documentation about empty collections vs collection skeletons (#1180)

* Clarify documentation about empty collections vs collection skeletons

* Update docs/docsite/rst/dev_guide/developing_collections_creating.rst

Author: s-hertel

docs/docsite/rst/dev_guide/developing_collections_creating.rst

@@ -6,7 +6,7 @@ Creating collections
 
 To create a collection:
 
-#. Create a :ref:`collection skeleton<creating_collections_skeleton>` with the ``ansible-galaxy collection init`` command.
+#. Create a :ref:`new collection<creating_new_collections>`, optionally using a custom :ref:`collection template<creating_collection_skeletons>`, with the ``ansible-galaxy collection init`` command.
 #. Add modules and other content to the collection.
 #. Build the collection into a collection artifact with :ref:`ansible-galaxy collection build<building_collections>`.
 #. Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish<publishing_collections>`.
@@ -44,10 +44,10 @@ There are a few special namespaces:
 
   The `local namespace <https://galaxy.ansible.com/ui/namespaces/local/>`__ does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the ``local`` namespace for collections that are locally on your machine or locally in your git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy.
 
-.. _creating_collections_skeleton:
+.. _creating_new_collections:
 
-Creating a collection skeleton
-==============================
+Creating a new collection
+=========================
 
 Create your collection skeleton in a path that includes ``ansible_collections``, for example `collections/ansible_collections/`.
 
@@ -66,19 +66,51 @@ It will create the structure ``[my_namespace]/[my_collection]/[collection skelet
 
 .. hint:: If Git is used for version control, the corresponding repository should be initialized in the collection directory.
 
-Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
+Once the collection exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
 
 Reference: the ``ansible-galaxy collection`` command
 
 Currently the ``ansible-galaxy collection`` command implements the following sub commands:
 
-* ``init``: Create a basic collection skeleton based on the default template included with Ansible or your own template.
+* ``init``: Create a basic collection based on the default template included with Ansible or your own template.
 * ``build``: Create a collection artifact that can be uploaded to Galaxy or your own repository.
 * ``publish``: Publish a built collection artifact to Galaxy.
 * ``install``: Install one or more collections.
 
 To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page.
 
+.. _creating_collection_skeletons:
+
+Creating a collection from a custom template
+============================================
+
+The built-in collection template is a simple example of a collection that works with ``ansible-core``, but if you want to simplify your development process you may want to create a custom collection template to pass to ``ansible-galaxy collection init``.
+
+A collection skeleton is a directory that looks like a collection directory but any ``.j2`` files (excluding those in ``templates/`` and ``roles/*/templates/``) will be templated by ``ansible-galaxy collection init``. The skeleton's ``galaxy.yml.j2`` file should use the variables ``namespace`` and ``collection_name`` which are derived from ``ansible-galaxy init namespace.collection_name``, and will populate the metadata in the initialized collection's ``galaxy.yml`` file. There are a few additional variables available by default (for example, ``version`` is ``1.0.0``), and these can be supplemented/overridden using ``--extra-vars``.
+
+An example ``galaxy.yml.j2`` file that accepts an optional dictionary variable ``dependencies`` could look like this:
+
+.. code-block:: yaml
+
+   namespace: {{ namespace }}
+   name: {{ collection_name }}
+   version: "{{ (version|quote) is version("0.0.0", operator="gt", version_type="semver")|ternary(version, undef("version must be a valid semantic version greater than 0.0.0")) }}"
+   dependencies: {{ dependencies|default({}, true) }}
+
+To initialize a collection using the new template, pass the path to the skeleton with ``ansible-galaxy collection init``:
+
+.. code-block:: bash
+
+   ansible_collections#> ansible-galaxy collection init --collection-skeleton /path/to/my/namespace/skeleton --extra-vars "@my_vars_file.json" my_namespace.my_collection
+
+.. note::
+
+   Before ``ansible-core`` 2.17, collection skeleton templating is limited to the few hardcoded variables including ``namespace``, ``collection_name``, and ``version``.
+
+.. note::
+
+   The default collection skeleton uses an internal filter ``comment_ify`` that isn't accessibly to ``--collection-skeleton``. Use ``ansible-doc -t filter|test --list`` to see available plugins.
+
 .. seealso::
 
    :ref:`collections`