Skip to content

Commit

Permalink
Refactor CLI (#253)
Browse files Browse the repository at this point in the history 
* init

* mo fixin

* more

* momo fixin

* momo fixin

* simple version

* Remove params

* Insert after removal

* Better messages

* f it

* Better messages

* rm general messages

* line length

* New tests

* Mass updates

* rm_bp

* Fix init

* comment out old

* Type fixes

* TYPE_CHECKING

* mv ARGCOMPLETE

* pylint fix

* Collection name checking

* Magic numbers

* Documentation updates

* Additional tests

* Type fix for capsys

* Type fix for capsys

* Additional tests

* Spelling fix

* Env fix

* Early exit for

* Fix help inconsistency with plugin and resource

* Remove demo files
  • Loading branch information
@cidrblock
cidrblock authored Jul 17, 2024
1 parent 2dc2e4f commit 26d3a25
Show file tree
Hide file tree
Showing 13 changed files with 1,092 additions and 210 deletions.
3 changes: 3 additions & 0 deletions .config/dictionary.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ argvalues
capsys
chakarborty
conftest
delenv
devcontainer
devfile
docsite
Expand All @@ -18,6 +19,8 @@ kubedock
levelname
libera
maxsplit
myproject
myorg
myuser
netcommon
nilashish
Expand Down
1 change: 1 addition & 0 deletions .config/requirements-test.in
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
argcomplete
black
coverage[toml]
mypy
Expand Down
1 change: 1 addition & 0 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ repos:
hooks:
- id: mypy
additional_dependencies:
- argcomplete
- jinja2
- pytest
- types-pyyaml
Expand Down
26 changes: 18 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,23 +18,33 @@ $ pip install ansible-creator

```shell
$ ansible-creator --help
usage: ansible-creator [-h] [--version] {init} ...
usage: ansible-creator [-h] command ...

Tool to scaffold Ansible Content. Get started by looking at the help text.
The fastest way to generate all your ansible content.

optional arguments:
-h, --help show this help message and exit
--version Print ansible-creator version and exit.
Positional arguments:
command
add Add resources to an existing Ansible project.
init Initialize a new Ansible project.

Commands:
{init} The subcommand to invoke.
init Initialize an Ansible Collection.
Options:
--version Print ansible-creator version and exit.
-h --help Show this help message and exit
```

## Usage

Full documentation on how to use this, along with it's integration with VS Code Ansible Extension can be found in https://ansible.readthedocs.io/projects/creator/.

## Command line completion

`ansible-creator` has experimental command line completion for common shells. Please ensure you have the `argcomplete` package installed and configured.

```shell
$ pip install argcomplete --user
$ activate-global-python-argcomplete --user
```

## Upcoming features

- Scaffold Ansible plugins of your choice with the `create` action.
Expand Down
6 changes: 1 addition & 5 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,7 @@ This documentation serves as a detailed guide for using ansible-creator, emphasi

## Upcoming Features

The `create` command is currently under development which will allow you scaffold ansible plugins of your choice.

!!! notice

Switch to the create [create branch](https://github.com/ansible/ansible-creator/tree/create) of the project to try it out!
The `add` command is currently under development which will allow you scaffold ansible plugins of your choice.

## Licensing

Expand Down
98 changes: 64 additions & 34 deletions docs/installing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,15 @@ The Command-Line Interface (CLI) for ansible-creator provides a straightforward

If command line is not your preferred method, you can also leverage the GUI interface within VS Code's Ansible extension that offers a more visually intuitive experience of ansible-creator. See [here](collection_creation.md).

## Command line completion

`ansible-creator` has experimental command line completion for common shells. Please ensure you have the `argcomplete` package installed and configured.

```shell
$ pip install argcomplete --user
$ activate-global-python-argcomplete --user
```

### General Usage

Get an overview of available commands and options by running:
Expand All @@ -26,48 +35,45 @@ Get an overview of available commands and options by running:
$ ansible-creator --help
```

### Initialize Ansible Collection (`init` subcommand)
### Initialize an Ansible collection project

The `init` command enables you to initialize an Ansible Collection to create a foundational structure for the project. Use the following command template:
The `init collection` command enables you to initialize an Ansible collection project. Use the following command template:

```console
$ ansible-creator init <collection-name> --init-path <path>
$ ansible-creator init collection <collection-name> <path>
```

#### Positional Argument(s)
#### Positional Arguments

| Parameter | Description |
| ---------- | -------------------------------------------------------------------- |
| collection | The name of the collection in the format `<namespace>.<collection>`. |
| Parameter | Description |
| --------------- | ------------------------------------------------------- |
| collection-name | The collection name in the format '<namespace>.<name>'. |
| path | The destination directory for the collection project. |

#### Optional Arguments

| Parameter | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| -h, --help | Show help message and exit. |
| --na, --no-ansi | Disable the use of ANSI codes for terminal color. |
| --lf, --log-file <file> | Log file to write to. |
| --ll, --log-level <level> | Log level (notset, debug, info, warning, error, critical) for file output. |
| --la, --log-append <bool> | Append to log file. |
| --json | Output messages as JSON. |
| -v, --verbose | Give more CLI output. Option is additive and can be used up to 3 times. |
| --project | Project type to scaffold. Valid choices are collection, ansible-project. |
| --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`. |
| --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`. |
| --init-path <path> | The path where the skeleton collection will be scaffolded (default is the current working directory). |
| --force | Force re-initialize the specified directory as an Ansible collection. |
| Sort flag | Long flag | Flag argument | Description |
| --------- | ------------ | ------------- | ----------------------------------------------------------------------------------------------------- |
| -f | --force | | Force re-initialize the specified directory as an Ansible collection. (default: False) |
| | --json | | Output messages as JSON (default: False) |
| --la | --log-append | bool | Append to log file. (choices: true, false) (default: true) |
| --lf | --log-file | file | Log file to write to. (default: ./ansible-creator.log) |
| --ll | --log-level | level | Log level for file output. (choices: notset, debug, info, warning, error, critical) (default: notset) |
| --na | --no-ansi | | Disable the use of ANSI codes for terminal color. (default: False) |
| -h | --help | | Show this help message and exit |
| -v | --verbosity | | Give more Cli output. Option is additive, and can be used up to 3 times. (default: 0) |

#### Example

```console
$ ansible-creator init testns.testname --init-path $HOME/collections/ansible_collections
$ ansible-creator init collection testns.testname $HOME/collections/ansible_collections
```

This command will scaffold the collection `testns.testname` at `/home/ansible-dev/collections/ansible_collections/testns/testname`

#### Generated Ansible Collection Structure

Running the init command generates an Ansible Collection with a comprehensive directory structure. Explore it using:
Running the `init collection` command generates an Ansible collection project with a comprehensive directory structure. Explore it using:

```console
$ tree -lla /home/ansible-dev/collections/ansible_collections/testns/testname
Expand Down Expand Up @@ -176,34 +182,58 @@ The scaffolded collection includes a `hello_world` filter plugin, along with a m
To run the `hello_world` integration test, follow these steps:

- Git initialize the repository containing the scaffolded collection with `git init`.
- `pip install ansible-core molecule pytest-xdist pytest-ansible`.
- `pip install ansible-dev-tools`.
- Invoke `pytest` from collection root.

### Initialize Ansible Project
### Initialize Ansible playbook project

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:
The `init playbook` command enables you to initialize an Ansible playbook project. Use the following command template:

#### Example
```console
$ ansible-creator init playbook <collection-name> <path>
```

#### Positional Arguments

| Parameter | Description |
| --------------- | --------------------------------------------------------------------------------- |
| collection-name | The name for the playbook adjacent collection in the format '<namespace>.<name>'. |
| path | The destination directory for the playbook project. |

#### Optional Arguments

| Sort flag | Long flag | Flag argument | Description |
| --------- | ------------ | ------------- | ----------------------------------------------------------------------------------------------------- |
| -f | --force | | Force re-initialize the specified directory as an Ansible collection. (default: False) |
| | --json | | Output messages as JSON (default: False) |
| --la | --log-append | bool | Append to log file. (choices: true, false) (default: true) |
| --lf | --log-file | file | Log file to write to. (default: ./ansible-creator.log) |
| --ll | --log-level | level | Log level for file output. (choices: notset, debug, info, warning, error, critical) (default: notset) |
| --na | --no-ansi | | Disable the use of ANSI codes for terminal color. (default: False) |
| -h | --help | | Show this help message and exit |
| -v | --verbosity | | Give more Cli output. Option is additive, and can be used up to 3 times. (default: 0) |

Example:

```console
$ ansible-creator init --project=ansible-project --scm-org=weather --scm-project=demo --init-path $HOME/path/to/scaffold/your/new_ansible_project
$ ansible-creator init playbook myorg.myproject $HOME/ansible-projects/playbook-project
```

This command will scaffold the ansible-project `new_ansible_project` at `/home/user/path/to/your/new_ansible_project`
This command will scaffold the new Ansible playbook project at `/home/user/ansible-projects/playbook-project`.

#### Generated Ansible Project Structure
#### Generated Ansible playbook project Structure

Running the init command with parameters `--project`, `--scm-org` and `--scm-project` generates an Ansible Project with a comprehensive directory structure. Explore it using:
Running the `init playbook` command generates an Ansible playbook project with a comprehensive directory structure. Explore it using:

```console
$ tree -la /home/user/path/to/your/new_ansible_project
$ tree -la /home/user/ansible-projects/playbook-project
.
├── ansible.cfg
├── ansible-navigator.yml
├── collections
│   ├── ansible_collections
│   │   └── weather
│   │   └── demo
│   │   └── myorg
│   │   └── myproject
│   │   ├── README.md
│   │   └── roles
│   │   └── run
Expand Down
Loading

0 comments on commit 26d3a25

Please sign in to comment.