aws-cloudformation / aws-cloudformation/cloudformation-cli
docs: `--use-docker` and `--no-docker` options of `cfn submit` are missing from the documentation
- 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
Assessment
This issue has not been assessed yet.