aws-cloudformation / aws-cloudformation/cloudformation-cli

docs: `--use-docker` and `--no-docker` options of `cfn submit` are missing from the documentation

Open
#1,119 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
336
Forks
172
Avg merge
3d 5m
Merged PRs (30d)
3

Description

## Summary

The `--use-docker` and `--no-docker` options were added to `cfn submit` in #970 (merged on May 4, 2023), but the documentation was not updated in the same change. As a result:

- `doc_source/resource-type-cli-submit.md` in this repository does not mention either option.
- The [public AWS documentation page](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-cli-submit.html) (which is generated from `doc_source/`) also does not mention them.

Users can discover these options only by running `cfn submit --help` or by reading the source code.

## Current state

In [`src/rpdk/core/submit.py`](https://github.com/aws-cloudformation/cloudformation-cli/blob/master/src/rpdk/core/submit.py), the options are registered like this:

```python
nodocker_group = parser.add_mutually_exclusive_group()
nodocker_group.add_argument(
"--use-docker",
action="store_true",
help="""Use docker for platform-independent packaging.
This is highly recommended unless you are experienced
with cross-platform packaging.""",
)
nodocker_group.add_argument(
"--no-docker",
action="store_true",
help="""Generally not recommended unless you are experienced
with cross-platform packaging.""",
)
```

But `doc_source/resource-type-cli-submit.md` lists only:

```
[--dry-run]
[--endpoint-url ]
[--profile ]
[--region ]
[--role-arn ]
[--no-role]
[--set-default]
```

## Proposed fix

Update `doc_source/resource-type-cli-submit.md` to:

1. Add `[--use-docker]` and `[--no-docker]` to the Synopsis block.
2. Add an entry for each option under the Options section, describing:
- What the option does.
- That `--use-docker` and `--no-docker` are mutually exclusive.
- That these flags override the `use_docker` / `no_docker` setting in `.rpdk-config`.

## Additional context

I'd like to pick this up and send a PR if that's okay.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.