Skip to content

Commit 17dc568

Browse files
shatakshiiiishatakshiiii
authored
Update documentation for ansible-project scaffolding (#133)
* Update docs for ansible-project scaffolding * Remove test.log file
1 parent 19b8a58 commit 17dc568

1 file changed

Lines changed: 75 additions & 11 deletions

File tree

‎docs/installing.md‎

Lines changed: 75 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -42,17 +42,20 @@ $ ansible-creator init <collection-name> --init-path <path>
4242

4343
#### Optional Arguments
4444

45-
| Parameter | Description |
46-
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
47-
| -h, --help | Show help message and exit. |
48-
| --na, --no-ansi | Disable the use of ANSI codes for terminal color. |
49-
| --lf, --log-file <file> | Log file to write to. |
50-
| --ll, --log-level <level> | Log level (notset, debug, info, warning, error, critical) for file output. |
51-
| --la, --log-append <bool> | Append to log file. |
52-
| --json | Output messages as JSON. |
53-
| -v, --verbose | Give more CLI output. Option is additive and can be used up to 3 times. |
54-
| --init-path <path> | The path where the skeleton collection will be scaffolded (default is the current working directory). |
55-
| --force | Force re-initialize the specified directory as an Ansible collection. |
45+
| Parameter | Description |
46+
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
47+
| -h, --help | Show help message and exit. |
48+
| --na, --no-ansi | Disable the use of ANSI codes for terminal color. |
49+
| --lf, --log-file <file> | Log file to write to. |
50+
| --ll, --log-level <level> | Log level (notset, debug, info, warning, error, critical) for file output. |
51+
| --la, --log-append <bool> | Append to log file. |
52+
| --json | Output messages as JSON. |
53+
| -v, --verbose | Give more CLI output. Option is additive and can be used up to 3 times. |
54+
| --project | Project type to scaffold. Valid choices are collection, ansible-project. |
55+
| --scm-org | The SCM org where the ansible-project will be hosted. This value is used as the namespace for the playbook adjacent collection. Required when `--project=ansible-project`. |
56+
| --scm-project | The SCM project where the ansible-project will be hosted. This value is used as the collection_name for the playbook adjacent collection. Required when `--project=ansible-project`. |
57+
| --init-path <path> | The path where the skeleton collection will be scaffolded (default is the current working directory). |
58+
| --force | Force re-initialize the specified directory as an Ansible collection. |
5659

5760
#### Example
5861

@@ -169,6 +172,67 @@ To run the `hello_world` integration test, follow these steps:
169172
- `pip install ansible-core molecule pytest-xdist pytest-ansible`.
170173
- Invoke `pytest` from collection root.
171174

175+
### Initialize Ansible Project
176+
177+
The `init` command along with parameters `--project`, `--scm-org` and `--scm-project` enables you to initialize an Ansible Project to create a foundational structure for the project. Use the following command template:
178+
179+
#### Example
180+
181+
```console
182+
$ ansible-creator init --project=ansible-project --scm-org=weather --scm-project=demo --init-path $HOME/path/to/scaffold/your/new_ansible_project
183+
```
184+
185+
This command will scaffold the ansible-project `new_ansible_project` at `/home/user/path/to/your/new_ansible_project`
186+
187+
#### Generated Ansible Project Structure
188+
189+
Running the init command with parameters `--project`, `--scm-org` and `--scm-project` generates an Ansible Project with a comprehensive directory structure. Explore it using:
190+
191+
```console
192+
$ tree -la /home/ansible-dev/collections/ansible_collections/testns/testname
193+
.
194+
├── ansible.cfg
195+
├── ansible-navigator.yml
196+
├── collections
197+
│   ├── ansible_collections
198+
│   │   └── weather
199+
│   │   └── demo
200+
│   │   ├── README.md
201+
│   │   └── roles
202+
│   │   └── run
203+
│   │   ├── README.md
204+
│   │   └── tasks
205+
│   │   └── main.yml
206+
│   └── requirements.yml
207+
├── .devcontainer
208+
│   ├── devcontainer.json
209+
│   ├── docker
210+
│   │   └── devcontainer.json
211+
│   └── podman
212+
│   └── devcontainer.json
213+
├── .github
214+
│   ├── ansible-code-bot.yml
215+
│   └── workflows
216+
│   └── tests.yml
217+
├── inventory
218+
│   ├── group_vars
219+
│   │   ├── all.yml
220+
│   │   └── web_servers.yml
221+
│   ├── hosts.yml
222+
│   └── host_vars
223+
│   ├── server1.yml
224+
│   ├── server2.yml
225+
│   ├── server3.yml
226+
│   ├── switch1.yml
227+
│   └── switch2.yml
228+
├── linux_playbook.yml
229+
├── network_playbook.yml
230+
├── README.md
231+
├── site.yml
232+
└── .vscode
233+
└── extensions.json
234+
```
235+
172236
It also comes equipped with Github Action Workflows that use [ansible-content-actions](https://github.com/marketplace/actions/ansible-content-actions) for testing and publishing the collection. For details on how to use these, please refer to the following:
173237

174238
- [Using the testing workflow](https://ansible.readthedocs.io/projects/dev-tools/user-guide/ci-setup/)

0 commit comments

Comments
 (0)