From 4a56bad48886d65d6a365846667f4434be86f555 Mon Sep 17 00:00:00 2001 From: Aine Riordan <44700011+ariordan-redhat@users.noreply.github.com> Date: Tue, 22 Oct 2024 18:14:29 +0100 Subject: [PATCH] AAP-33897 Devtools Add scaffolding collections chapter (#2404) --- .../assembly-devtools-ansible-sign.adoc | 24 ++++++ .../devtools/assembly-devtools-builder.adoc | 24 ++++++ ...ly-devtools-create-plugins-collection.adoc | 25 ++++++ .../devtools/assembly-devtools-lint.adoc | 24 ++++++ .../devtools/assembly-devtools-molecule.adoc | 24 ++++++ .../devtools/assembly-devtools-navigator.adoc | 24 ++++++ .../assembly-devtools-pytest-ansible.adoc | 24 ++++++ .../assembly-devtools-tox-ansible.adoc | 24 ++++++ .../con-devtools-plan-plugins-collection.adoc | 7 ++ ...ools-plugins-collection-prerequisites.adoc | 15 ++++ ...vtools-roles-collection-prerequisites.adoc | 2 +- ...-devtools-scaffold-plugins-collection.adoc | 78 +++++++++++++++++++ .../develop-automation-content/master.adoc | 14 ++++ 13 files changed, 308 insertions(+), 1 deletion(-) create mode 100644 downstream/assemblies/devtools/assembly-devtools-ansible-sign.adoc create mode 100644 downstream/assemblies/devtools/assembly-devtools-builder.adoc create mode 100644 downstream/assemblies/devtools/assembly-devtools-create-plugins-collection.adoc create mode 100644 downstream/assemblies/devtools/assembly-devtools-lint.adoc create mode 100644 downstream/assemblies/devtools/assembly-devtools-molecule.adoc create mode 100644 downstream/assemblies/devtools/assembly-devtools-navigator.adoc create mode 100644 downstream/assemblies/devtools/assembly-devtools-pytest-ansible.adoc create mode 100644 downstream/assemblies/devtools/assembly-devtools-tox-ansible.adoc create mode 100644 downstream/modules/devtools/con-devtools-plan-plugins-collection.adoc create mode 100644 downstream/modules/devtools/con-devtools-plugins-collection-prerequisites.adoc create mode 100644 downstream/modules/devtools/proc-devtools-scaffold-plugins-collection.adoc diff --git a/downstream/assemblies/devtools/assembly-devtools-ansible-sign.adoc b/downstream/assemblies/devtools/assembly-devtools-ansible-sign.adoc new file mode 100644 index 0000000000..f768ae9fbb --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-ansible-sign.adoc @@ -0,0 +1,24 @@ +ifdef::context[:parent-context-of-devtools-ansible-sign: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-ansible-sign"] +endif::[] +ifdef::context[] +[id="devtools-ansible-sign_{context}"] +endif::[] + += Working with ansible-sign + +:context: devtools-ansible-sign + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +Working with ansible-sign + +// include::devtools/proc-devtools-zzz.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-ansible-sign[:context: {parent-context-of-devtools-ansible-sign}] +ifndef::parent-context-of-devtools-ansible-sign[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-devtools-builder.adoc b/downstream/assemblies/devtools/assembly-devtools-builder.adoc new file mode 100644 index 0000000000..72107d357f --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-builder.adoc @@ -0,0 +1,24 @@ +ifdef::context[:parent-context-of-devtools-builder: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-builder"] +endif::[] +ifdef::context[] +[id="devtools-builder_{context}"] +endif::[] + += Working with {Builder} + +:context: devtools-builder + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +Working with {Builder} + +// include::devtools/proc-devtools-zzz.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-builder[:context: {parent-context-of-devtools-builder}] +ifndef::parent-context-of-devtools-builder[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-devtools-create-plugins-collection.adoc b/downstream/assemblies/devtools/assembly-devtools-create-plugins-collection.adoc new file mode 100644 index 0000000000..edb72a87d6 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-create-plugins-collection.adoc @@ -0,0 +1,25 @@ +ifdef::context[:parent-context-of-devtools-create-plugins-collection: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-create-plugins-collection"] +endif::[] +ifdef::context[] +[id="devtools-create-plugins-collection_{context}"] +endif::[] + += Creating a collection for distributing plug-ins and modules + +:context: devtools-create-plugins-collection + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +include::devtools/con-devtools-plan-plugins-collection.adoc[leveloffset=+1] +include::devtools/con-devtools-plugins-collection-prerequisites.adoc[leveloffset=+1] + +include::devtools/proc-devtools-scaffold-roles-collection.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-create-plugins-collection[:context: {parent-context-of-devtools-create-plugins-collection}] +ifndef::parent-context-of-devtools-create-plugins-collection[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-devtools-lint.adoc b/downstream/assemblies/devtools/assembly-devtools-lint.adoc new file mode 100644 index 0000000000..71efd2f25c --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-lint.adoc @@ -0,0 +1,24 @@ +ifdef::context[:parent-context-of-devtools-lint: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-lint"] +endif::[] +ifdef::context[] +[id="devtools-lint_{context}"] +endif::[] + += Working with ansible-lint + +:context: devtools-lint + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +Working with ansible-lint + +// include::devtools/proc-devtools-zzz.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-lint[:context: {parent-context-of-devtools-lint}] +ifndef::parent-context-of-devtools-lint[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-devtools-molecule.adoc b/downstream/assemblies/devtools/assembly-devtools-molecule.adoc new file mode 100644 index 0000000000..c2c697b373 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-molecule.adoc @@ -0,0 +1,24 @@ +ifdef::context[:parent-context-of-devtools-molecule: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-molecule"] +endif::[] +ifdef::context[] +[id="devtools-molecule_{context}"] +endif::[] + += Working with Molecule + +:context: devtools-molecule + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +Working with Molecule + +// include::devtools/proc-devtools-zzz.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-molecule[:context: {parent-context-of-devtools-molecule}] +ifndef::parent-context-of-devtools-molecule[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-devtools-navigator.adoc b/downstream/assemblies/devtools/assembly-devtools-navigator.adoc new file mode 100644 index 0000000000..d5a8a4cac3 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-navigator.adoc @@ -0,0 +1,24 @@ +ifdef::context[:parent-context-of-devtools-navigator: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-navigator"] +endif::[] +ifdef::context[] +[id="devtools-navigator_{context}"] +endif::[] + += Working with {Navigator} + +:context: devtools-navigator + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +Working with {Navigator} + +// include::devtools/proc-devtools-zzz.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-navigator[:context: {parent-context-of-devtools-navigator}] +ifndef::parent-context-of-devtools-navigator[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-devtools-pytest-ansible.adoc b/downstream/assemblies/devtools/assembly-devtools-pytest-ansible.adoc new file mode 100644 index 0000000000..9c5921fc14 --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-pytest-ansible.adoc @@ -0,0 +1,24 @@ +ifdef::context[:parent-context-of-devtools-pytest-ansible: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-pytest-ansible"] +endif::[] +ifdef::context[] +[id="devtools-pytest-ansible_{context}"] +endif::[] + += Working with pytest-ansible + +:context: devtools-pytest-ansible + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +Working with pytest-ansible + +// include::devtools/proc-devtools-zzz.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-pytest-ansible[:context: {parent-context-of-devtools-pytest-ansible}] +ifndef::parent-context-of-devtools-pytest-ansible[:!context:] + diff --git a/downstream/assemblies/devtools/assembly-devtools-tox-ansible.adoc b/downstream/assemblies/devtools/assembly-devtools-tox-ansible.adoc new file mode 100644 index 0000000000..c7be118e5b --- /dev/null +++ b/downstream/assemblies/devtools/assembly-devtools-tox-ansible.adoc @@ -0,0 +1,24 @@ +ifdef::context[:parent-context-of-devtools-tox-ansible: {context}] + +:_mod-docs-content-type: ASSEMBLY + +ifndef::context[] +[id="devtools-tox-ansible"] +endif::[] +ifdef::context[] +[id="devtools-tox-ansible_{context}"] +endif::[] + += Working with tox-ansible + +:context: devtools-tox-ansible + +// You must move roles into collections if you want to use them in {PlatformNameShort}. + +Working with tox-ansible + +// include::devtools/proc-devtools-zzz.adoc[leveloffset=+1] + +ifdef::parent-context-of-devtools-tox-ansible[:context: {parent-context-of-devtools-tox-ansible}] +ifndef::parent-context-of-devtools-tox-ansible[:!context:] + diff --git a/downstream/modules/devtools/con-devtools-plan-plugins-collection.adoc b/downstream/modules/devtools/con-devtools-plan-plugins-collection.adoc new file mode 100644 index 0000000000..53e4aba012 --- /dev/null +++ b/downstream/modules/devtools/con-devtools-plan-plugins-collection.adoc @@ -0,0 +1,7 @@ +:_mod-docs-content-type: CONCEPT + +[id="plan-plugins-collection_{context}"] += Planning your collection of plugins and modules + +// Organize smaller bundles of curated automation into separate collections for specific functions, rather than creating one big general collection for all of your roles. + diff --git a/downstream/modules/devtools/con-devtools-plugins-collection-prerequisites.adoc b/downstream/modules/devtools/con-devtools-plugins-collection-prerequisites.adoc new file mode 100644 index 0000000000..dec439c3d4 --- /dev/null +++ b/downstream/modules/devtools/con-devtools-plugins-collection-prerequisites.adoc @@ -0,0 +1,15 @@ +:_mod-docs-content-type: CONCEPT + +[id="devtools-plugins-collection-prerequisites_{context}"] += Prerequisites + +* You have installed {VSCode} and the Ansible extension. +* You have installed the Microsoft Dev Containers extension in {VSCode}. +* You have installed {ToolsName}. +* You have installed a containerization platform, for example Podman, Podman Desktop, Docker, or Docker Desktop. +* You have a Red Hat account and you can log in to the Red Hat container registry at `registry.redhat.io`. +For information about logging in to `registry.redhat.io`, see +xref:devtools-setup-registry-redhat-io_installing-devtools[Authenticating with the Red Hat container registry]. +// * Considerations about environments / isolation (ADE / devcontainer files) + + diff --git a/downstream/modules/devtools/con-devtools-roles-collection-prerequisites.adoc b/downstream/modules/devtools/con-devtools-roles-collection-prerequisites.adoc index 2b30223c52..a641a6b5de 100644 --- a/downstream/modules/devtools/con-devtools-roles-collection-prerequisites.adoc +++ b/downstream/modules/devtools/con-devtools-roles-collection-prerequisites.adoc @@ -4,7 +4,7 @@ = Prerequisites * You have installed {VSCode} and the Ansible extension. -* You have installed the Microsoft Dev Containers extension in {{VSCode}. +* You have installed the Microsoft Dev Containers extension in {VSCode}. * You have installed {ToolsName}. * You have installed a containerization platform, for example Podman, Podman Desktop, Docker, or Docker Desktop. * You have a Red Hat account and you can log in to the Red Hat container registry at `registry.redhat.io`. diff --git a/downstream/modules/devtools/proc-devtools-scaffold-plugins-collection.adoc b/downstream/modules/devtools/proc-devtools-scaffold-plugins-collection.adoc new file mode 100644 index 0000000000..9b8360a7b9 --- /dev/null +++ b/downstream/modules/devtools/proc-devtools-scaffold-plugins-collection.adoc @@ -0,0 +1,78 @@ +:_mod-docs-content-type: PROCEDURE + +[id="devtools-scaffold-plugins-collection_{context}"] += Scaffolding a collection for your plug-ins and modules + +You can scaffold a collection for plug-ins and modules from the Ansible extension in {VSCode}. + +.Procedure + +. Open {VSCode}. +. Navigate to the directory where you want to create your collection. +. Click the Ansible icon in the {VSCode} activity bar to open the Ansible extension. +. Select *Get started* in the *Ansible content creator* section. ++ +The *Ansible content creator* tab opens. +. In the *Create* section, click *Ansible collection project*. ++ +The *Create new Ansible project* tab opens. +. In the form in the *Create Ansible project* tab, enter the following: +** *Namespace*: Enter a name for your namespace, for example `company_namespace`. +** *Collection*: Enter a name for your collection, for example, `myapp_network`. +** *Init path*: Enter the path to the directory where you want to scaffold your new collection. ++ +If you enter an existing directory name, the scaffolding process overwrites the contents of that directory. +The scaffold process only allows you to use an existing directory if you enable the Force option. + +*** If you are using the containerized version of Ansible development tools, +the destination directory path is relative to the container, not a path in your local system. +To discover the current directory name in the container, run the pwd command in a terminal in {VSCode}. +If the current directory in the container is `workspaces`, enter `workspaces//collections`. +*** If you are using a locally installed version of Ansible Dev tools, +enter the full path to the directory, for example `/user//path/to/`. +. Click btn:[Create]. + +.Verification + +The following message appears in the *Logs* pane of the *Create Ansible collection* tab. +// In this example, the destination directory name is + +---- +--------------------- ansible-creator logs --------------------- + + Note: collection company_namespace.myapp_network created at /path/to/collections/directory +---- + +The following directories and files are created in your `collections/` directory: + +---- +├── .devcontainer +├── .github +├── .gitignore +├── .isort.cfg +├── .pre-commit-config.yaml +├── .prettierignore +├── .vscode +├── CHANGELOG.rst +├── CODE_OF_CONDUCT.md +├── CONTRIBUTING +├── LICENSE +├── MAINTAINERS +├── README.md +├── changelogs +├── devfile.yaml +├── docs +├── extensions +├── galaxy.yml +├── meta +├── plugins +├── pyproject.toml +├── requirements.txt +├── roles +├── test-requirements.txt +├── tests +└── tox-ansible.ini + +---- + + diff --git a/downstream/titles/develop-automation-content/master.adoc b/downstream/titles/develop-automation-content/master.adoc index 1038dddf7c..d68dc34451 100644 --- a/downstream/titles/develop-automation-content/master.adoc +++ b/downstream/titles/develop-automation-content/master.adoc @@ -29,4 +29,18 @@ include::devtools/assembly-publishing-playbook-collection-aap.adoc[leveloffset=+ include::devtools/assembly-devtools-develop-collections.adoc[leveloffset=+1] include::devtools/assembly-devtools-create-roles-collection.adoc[leveloffset=+1] +include::devtools/assembly-devtools-create-plugins-collection.adoc[leveloffset=+1] + +// Components + + +include::devtools/assembly-devtools-navigator.adoc[leveloffset=+1] +include::devtools/assembly-devtools-builder.adoc[leveloffset=+1] + +include::devtools/assembly-devtools-lint.adoc[leveloffset=+1] +include::devtools/assembly-devtools-molecule.adoc[leveloffset=+1] + +include::devtools/assembly-devtools-tox-ansible.adoc[leveloffset=+1] +include::devtools/assembly-devtools-pytest-ansible.adoc[leveloffset=+1] +include::devtools/assembly-devtools-ansible-sign.adoc[leveloffset=+1]