Merge pull request #8 from NilashishC/updates_1

Updates to README and init structure

.config/dictionary.txt

@@ -116,7 +116,13 @@ templated
 templating
 testhost
 testname
+testns
+notesdir
+antsibull
+flatmap
+Libera
 topbar
+docsite
 tracebacks
 truecolor
 usefixtures

README.md

@@ -0,0 +1,117 @@
+# ansible-creator
+
+A CLI tool for scaffolding Ansible Content.
+
+## Installation
+
+```
+$ pip install git+https://github.com/NilashishC/ansible-creator
+```
+
+## Usage
+
+```
+$ ansible-creator --help
+usage: ansible-creator [-h] [--version] {init} ...
+
+Tool to scaffold Ansible Content. Get started by looking at the help text.
+
+positional arguments:
+   {init}               The command to invoke.
+    init                Initialize an Ansible Collection.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --version             Print ansible-creator version and exit.
+```
+
+### Initialize an Ansible Collection skeleton with 'init'
+
+```
+$ ansible-creator init --help
+usage: ansible-creator init [-h] [--verbose] [--init-path INIT_PATH] [--force] collection_name
+
+Creates the skeleton framework of an Ansible collection.
+
+positional arguments:
+  collection_name       The collection name in the format ``<namespace>.<collection>``.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --verbose             Increase output verbosity
+  --init-path INIT_PATH
+                        The path in which the skeleton collection will be created.
+                        The default is the current working directory.
+  --force               Force re-initialize the specified directory as an Ansible collection.
+```
+
+```
+$ ansible-creator init namespace.name --init-path $HOME
+INFO     starting requested action 'init'
+INFO     collection namespace.name successfully created at /home/ansible
+```
+
+Running the above command generates an Ansible Collection with the following structure:
+
+```
+$ tree -lla /home/ansible/namespace/name
+/home/ansible/namespace/name
+├── CHANGELOG.rst
+├── changelogs
+│   └── config.yaml
+├── docs
+│   ├── docsite
+│   │   └── links.yml
+│   └── .keep
+├── galaxy.yml
+├── .github
+│   └── workflows
+│       └── test.yml
+├── .isort.cfg
+├── LICENSE
+├── meta
+│   └── runtime.yml
+├── plugins
+│   ├── action
+│   │   └── __init__.py
+│   ├── cache
+│   │   └── __init__.py
+│   ├── filter
+│   │   └── __init__.py
+│   ├── inventory
+│   │   └── __init__.py
+│   ├── modules
+│   │   └── __init__.py
+│   ├── module_utils
+│   │   └── __init__.py
+│   ├── plugin_utils
+│   │   └── __init__.py
+│   ├── sub_plugins
+│   │   └── __init__.py
+│   └── test
+│       └── __init__.py
+├── .pre-commit-config.yaml
+├── .prettierignore
+├── pyproject.toml
+├── README.md
+├── tests
+│   ├── .gitignore
+│   ├── integration
+│   │   └── targets
+│   │       └── .keep
+│   └── unit
+│       └── .keep
+└── .vscode
+    └── extensions.json
+```
+
+### Upcoming features
+
+- Scaffold Ansible plugins of your choice with the `create` action.
+  Switch to the [create](https://github.com/NilashishC/ansible-creator/tree/create) branch and try it out!
+
+## Licensing
+
+GNU General Public License v3.0 or later.
+
+See [LICENSE](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text.

src/ansible_creator/actions/create.py

@@ -28,7 +28,7 @@ def __init__(self: CreatorCreate, **kwargs: str) -> None:
 
         :param **args: A dictionary containing Create options.
         """
-        self.file_path: str = kwargs["file"]
+        self._file_path: str = kwargs["file"]
 
     def run(self: CreatorCreate) -> None:
         """Start scaffolding the specified content(s).
@@ -93,7 +93,7 @@ def load_config(self: CreatorCreate) -> dict:
         """
         content_def = {}
         file_path = os.path.abspath(
-            os.path.expanduser(os.path.expandvars(self.file_path)),
+            os.path.expanduser(os.path.expandvars(self._file_path)),
         )
 
         logger.info("attempting to load the content definition file %s", file_path)

src/ansible_creator/actions/init.py

@@ -28,6 +28,7 @@ def __init__(self: CreatorInit, **kwargs: str) -> None:
             os.path.expanduser(os.path.expandvars(kwargs["init_path"])),
         )
         self._force = kwargs["force"]
+        self._creator_version = kwargs["creator_version"]
         self._templar = Templar()
 
     def run(self: CreatorInit) -> None:
@@ -50,8 +51,8 @@ def run(self: CreatorInit) -> None:
             if not self._force:
                 msg = (
                     f"The directory {col_path} already exists.\n"
-                    "{'':<9}You can use --force to re-initialize this directory,"
-                    "\n{'':<9}However it will delete ALL existing contents in it."
+                    f"{'':<9}You can use --force to re-initialize this directory,"
+                    f"\n{'':<9}However it will delete ALL existing contents in it."
                 )
                 raise CreatorError(msg)
 
@@ -81,6 +82,7 @@ def run(self: CreatorInit) -> None:
             template_data={
                 "namespace": self._namespace,
                 "collection_name": self._collection_name,
+                "creator_version": self._creator_version,
             },
         )
 

src/ansible_creator/cli.py

@@ -149,6 +149,7 @@ def run(self: AnsibleCreatorCLI) -> None:
             self.logger.info("starting requested action '%s'", action)
             action_class = getattr(import_module(action_modules), action_prefix)
             self.logger.debug("found action class %s", action_class)
+            cli_args.update({"creator_version": __version__})
             action_class(**cli_args).run()
         except CreatorError as exc:
             self.logger.error(str(exc))

src/ansible_creator/resources/new_collection/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["redhat.ansible"]
+}

src/ansible_creator/resources/new_collection/CHANGELOG.rst

@@ -0,0 +1,6 @@
+This should be updated by antsibull-changelog. Do not edit this manually!
+
+See https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst for
+information on how to use antsibull-changelog.
+
+Check out ``changelogs/config.yaml`` for its configuration. You need to change at least the ``title`` field in there.

src/ansible_creator/resources/new_collection/LICENSE.j2

@@ -1,4 +1,4 @@
-  GNU GENERAL PUBLIC LICENSE
+                    GNU GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 
  Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>

src/ansible_creator/resources/new_collection/README.md.j2

@@ -4,7 +4,7 @@ This repository contains the `{{ namespace }}.{{ collection_name }}` Ansible Col
 
 ## Tested with Ansible
 
-Tested with ansible-core >=2.12 releases and the current development version of ansible-core.
+Tested with ansible-core >=2.13 releases and the current development version of ansible-core.
 
 ## External requirements
 
@@ -40,8 +40,28 @@ ansible-galaxy collection install {{ namespace }}.{{ collection_name }}:==X.Y.Z
 
 See [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details.
 
+## Release notes
+
+See the [changelog](https://github.com/ansible-collections/REPONAMEHERE/tree/main/CHANGELOG.rst).
+
+## Roadmap
+
+<!-- Optional. Include the roadmap for this collection, and the proposed release/versioning strategy so users can anticipate the upgrade/update cycle. -->
+
+## More information
+
+<!-- List out where the user can find additional information, such as working group meeting times, slack/IRC channels, or documentation for the product this collection automates. At a minimum, link to: -->
+
+- [Ansible Collection overview](https://github.com/ansible-collections/overview)
+- [Ansible User guide](https://docs.ansible.com/ansible/devel/user_guide/index.html)
+- [Ansible Developer guide](https://docs.ansible.com/ansible/devel/dev_guide/index.html)
+- [Ansible Collections Checklist](https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst)
+- [Ansible Community code of conduct](https://docs.ansible.com/ansible/devel/community/code_of_conduct.html)
+- [The Bullhorn (the Ansible Contributor newsletter)](https://us19.campaign-archive.com/home/?u=56d874e027110e35dea0e03c1&id=d6635f5420)
+- [News for Maintainers](https://github.com/ansible-collections/news-for-maintainers)
+
 ## Licensing
 
 GNU General Public License v3.0 or later.
 
-See [COPYING](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text.
+See [LICENSE](https://www.gnu.org/licenses/gpl-3.0.txt) to see the full text.

src/ansible_creator/resources/new_collection/changelogs/config.yaml

@@ -0,0 +1,32 @@
+changelog_filename_template: ../CHANGELOG.rst
+changelog_filename_version_depth: 0
+changes_file: changelog.yaml
+changes_format: combined
+keep_fragments: false
+mention_ancestor: true
+new_plugins_after_name: removed_features
+notesdir: fragments
+prelude_section_name: release_summary
+prelude_section_title: Release Summary
+flatmap: true
+sections:
+  - - major_changes
+    - Major Changes
+  - - minor_changes
+    - Minor Changes
+  - - breaking_changes
+    - Breaking Changes / Porting Guide
+  - - deprecated_features
+    - Deprecated Features
+  - - removed_features
+    - Removed Features (previously deprecated)
+  - - security_fixes
+    - Security Fixes
+  - - bugfixes
+    - Bugfixes
+  - - known_issues
+    - Known Issues
+  - - doc_changes
+    - Documentation Changes
+title: "{{ namespace|capitalize }} {{ collection_name|capitalize }} Collection"
+trivial_section_name: trivial

src/ansible_creator/resources/new_collection/docs/docsite/links.yml

@@ -0,0 +1,47 @@
+---
+# This will make sure that plugin and module documentation gets Edit on GitHub links
+# that allow users to directly create a PR for this plugin or module in GitHub's UI.
+# Remove this section if the collection repository is not on GitHub, or if you do not
+# want this functionality for your collection.
+edit_on_github:
+  # TO-DO: Update this if your collection lives in a different GitHub organization.
+  repository: ansible-collections/{{ namespace }}.{{ collection_name }}
+  branch: main
+  # If your collection root (the directory containing galaxy.yml) does not coincide with your
+  # repository's root, you have to specify the path to the collection root here. For example,
+  # if the collection root is in a subdirectory ansible_collections/community/REPO_NAME
+  # in your repository, you have to set path_prefix to 'ansible_collections/community/REPO_NAME'.
+  path_prefix: ""
+
+# Here you can add arbitrary extra links. Please keep the number of links down to a
+# minimum! Also please keep the description short, since this will be the text put on
+# a button.
+#
+# Also note that some links are automatically added from information in galaxy.yml.
+# The following are automatically added:
+#   1. A link to the issue tracker (if `issues` is specified);
+#   2. A link to the homepage (if `homepage` is specified and does not equal the
+#      `documentation` or `repository` link);
+#   3. A link to the collection's repository (if `repository` is specified).
+
+extra_links:
+  - description: Report an issue
+    # TO-DO: Update this if your collection lives in a different GitHub organization.
+    url: https://github.com/ansible-collections/{{ namespace }}.{{ collection_name }}/issues/new/choose
+
+# Specify communication channels for your collection. We suggest to not specify more
+# than one place for communication per communication tool to avoid confusion.
+communication:
+  matrix_rooms:
+    - topic: General usage and support questions
+      room: "#users:ansible.im"
+  irc_channels:
+    - topic: General usage and support questions
+      network: Libera
+      channel: "#ansible"
+  mailing_lists:
+    - topic: Ansible Project List
+      url: https://groups.google.com/g/ansible-project
+      # You can also add a `subscribe` field with an URI that allows to subscribe
+      # to the mailing list. For lists on https://groups.google.com/ a subscribe link is
+      # automatically generated.

src/ansible_creator/resources/new_collection/galaxy.yml.j2

@@ -1,3 +1,7 @@
+# This collection is initialized by https://github.com/ansible-community/ansible_creator {{ creator_version }}
+
+# See https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html
+
 namespace: "{{ namespace }}"
 name: "{{ collection_name }}"
 version: 1.0.0
@@ -19,7 +23,9 @@ issues: http://example.com/issue/tracker
 # artifact. A pattern is matched from the relative path of the file or directory of the collection directory. This
 # uses 'fnmatch' to match the files or directories. Some directories and files like 'galaxy.yml', '*.pyc', '*.retry',
 # and '.git' are always filtered. Mutually exclusive with 'manifest'
-build_ignore: []
+build_ignore:
+  - .gitignore
+  - changelogs/.plugin-cache.yaml
 
 # A dict controlling use of manifest directives used in building the collection artifact. The key 'directives' is a
 # list of MANIFEST.in style

src/ansible_creator/resources/new_collection/meta/runtime.yml

@@ -0,0 +1,2 @@
+---
+requires_ansible: ">=2.13.0"

src/ansible_creator/resources/new_collection/tests/.gitignore

@@ -0,0 +1 @@
+output/

src/ansible_creator/resources/new_collection/tests/unit/.keep

@@ -0,0 +1,6 @@
+Will be updated by antsibull-changelog. Do not edit this manually!
+
+See https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst for information
+on how to use antsibull-changelog.
+
+Check out changelogs/config.yaml for its configuration. You need to change at least the title field in there.