diff --git a/MANIFEST.in b/MANIFEST.in index 9e436f81..8bdba992 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include README.rst +include README.md include LICENSE graft src diff --git a/README.md b/README.md new file mode 100644 index 00000000..35f8046a --- /dev/null +++ b/README.md @@ -0,0 +1,86 @@ +# AWS CloudFormation CLI + +The CloudFormation CLI (cfn) allows you to author your own resource providers that can be used by CloudFormation. + +## Usage + +### Documentation + +Primary documentation for the CloudFormation CLI can be found at the [AWS Documentation](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-types.html) site. + +### Installation + +This tool can be installed using [pip](https://pypi.org/project/pip/) from the Python Package Index (PyPI). It requires Python 3. The tool requires at least one language plugin. The language plugins are also available on PyPI and as such can be installed all at once: + +```bash +pip install cloudformation-cli cloudformation-cli-java-plugin cloudformation-cli-go-plugin +``` + + +### Command: init + +To create a project in the current directory, use the `init` command. A wizard will guide you through the creation. + +```bash +cfn init +``` + +### Command: generate + +To refresh auto-generated code, use the `generate` command. Usually, plugins try to integrate this command in the native build flow, so please consult a plugin's README to see if this is necessary. + +```bash +cfn generate +``` + +## Development + +For developing, it's strongly suggested to install the development dependencies inside a virtual environment. (This isn't required if you just want to use this tool.) + +```bash +python3 -m venv env +source env/bin/activate +pip install -e . -r requirements.txt +pre-commit install +``` + +You will also need to install a language plugin, such as [the Java language plugin](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin), also via `pip install`. For example, assuming the plugin is checked out in the same parent directory as this repository: + +```bash +pip install -e ../cloudformation-cli-java-plugin +``` + +Linting and running unit tests is done via [pre-commit](https://pre-commit.com/), and so is performed automatically on commit. The continuous integration also runs these checks. Manual options are available so you don't have to commit): + +```bash +# run all hooks on all files, mirrors what the CI runs +pre-commit run --all-files +# run unit tests only. can also be used for other hooks, e.g. black, flake8, pylint-local +pre-commit run pytest-local +``` + +If you want to generate an HTML coverage report afterwards, run `coverage html`. The report is output to `htmlcov/index.html`. + +## Plugin system + +New language plugins can be independently developed. As long as they declare the appropriate entry point and are installed in the same environment, they can even be completely separate codebases. For example, a plugin for Groovy might have the following entry point: + +```python +entry_points={ + "rpdk.v1.languages": ["groovy = rpdk.groovy:GroovyLanguagePlugin"], +}, +``` + +Plugins must provide the same interface as `LanguagePlugin` (in `plugin_base.py`). And they may inherit from `LanguagePlugin` for the helper methods - but this is not necessary. As long as the class has the same methods, it will work as a plugin. + +### Supported plugins + +| Language | Status | Github | PyPI | +| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| Java | Available | [cloudformation-cli-java-plugin](https://github.com/aws-cloudformation/cloudformation-cli-java-plugin/) | [cloudformation-cli-java-plugin](https://pypi.org/project/cloudformation-cli-java-plugin/) | +| Go | Available | [cloudformation-cli-go-plugin](https://github.com/aws-cloudformation/cloudformation-cli-go-plugin/) | [cloudformation-cli-go-plugin](https://pypi.org/project/cloudformation-cli-go-plugin/) | +| Python | Developer Preview | [cloudformation-cli-python-plugin](https://github.com/aws-cloudformation/cloudformation-cli-python-plugin/) | N/A | + +## License + +This library is licensed under the Apache 2.0 License. diff --git a/README.rst b/README.rst deleted file mode 100644 index 990f3a3f..00000000 --- a/README.rst +++ /dev/null @@ -1,108 +0,0 @@ -AWS CloudFormation CLI -====================== - -The CloudFormation CLI (cfn) allows you to author your own resource providers that can be used by CloudFormation. - -Usage ------ -Documentation -^^^^^^^^^^^^^ - -Primary documentation for the CloudFormation CLI can be found at the `AWS Documentation `_ site. - -Installation -^^^^^^^^^^^^ - -This tool can be installed using `pip `_ from -the Python Package Index (PyPI). It requires Python 3. The tool requires at least one language plugin. The language plugins are also available on PyPI and as such can be installed all at once: - -.. code-block:: bash - - pip install cloudformation-cli cloudformation-cli-java-plugin cloudformation-cli-go-plugin - - - -Command: init -^^^^^^^^^^^^^ - -To create a project in the current directory, use the ``init`` command. A wizard will guide you through the creation. - -.. code-block:: bash - - cfn init - -Command: generate -^^^^^^^^^^^^^^^^^ - -To refresh auto-generated code, use the ``generate`` command. Usually, plugins try to integrate this command in the native build flow, so please consult a plugin's README to see if this is necessary. - -.. code-block:: bash - - cfn generate - -Development ------------ - -For developing, it's strongly suggested to install the development dependencies -inside a virtual environment. (This isn't required if you just want to use this -tool.) - -.. code-block:: bash - - python3 -m venv env - source env/bin/activate - pip install -e . -r requirements.txt - pre-commit install - -You will also need to install a language plugin, such as `the Java language plugin `_, also via `pip install`. For example, assuming the plugin is checked out in the same parent directory as this repository: - -.. code-block:: bash - - pip install -e ../cloudformation-cli-java-plugin - -Linting and running unit tests is done via `pre-commit `_, and so is performed automatically on commit. The continuous integration also runs these checks. Manual options are available so you don't have to commit): - -.. code-block:: bash - - # run all hooks on all files, mirrors what the CI runs - pre-commit run --all-files - # run unit tests only. can also be used for other hooks, e.g. black, flake8, pylint-local - pre-commit run pytest-local - - -If you want to generate an HTML coverage report afterwards, run -``coverage html``. The report is output to ``htmlcov/index.html``. - -Plugin system -------------- - -New language plugins can be independently developed. As long as they declare -the appropriate entry point and are installed in the same environment, they can -even be completely separate codebases. For example, a plugin for Groovy might -have the following entry point: - -.. code-block:: python - - entry_points={ - "rpdk.v1.languages": ["groovy = rpdk.groovy:GroovyLanguagePlugin"], - }, - -Plugins must provide the same interface as ``LanguagePlugin`` (in -``plugin_base.py``). And they may inherit from ``LanguagePlugin`` for the helper -methods - but this is not necessary. As long as the class has the same methods, -it will work as a plugin. - -Supported plugins -^^^^^^^^^^^^^^^^^ -======== ================= ======================================================================================================================= ============================================================================================ -Language Status Github PyPI -======== ================= ======================================================================================================================= ============================================================================================ -Java Available `cloudformation-cli-java-plugin `_ `cloudformation-cli-java-plugin `_ -Go Available `cloudformation-cli-go-plugin `_ `cloudformation-cli-go-plugin `_ -Python Developer Preview `cloudformation-cli-python-plugin `_ N/A -======== ================= ======================================================================================================================= ============================================================================================ - -License -------- - -This library is licensed under the Apache 2.0 License. diff --git a/requirements.txt b/requirements.txt index 29e5385f..31a37895 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +1,6 @@ # better interactive session, debugger ipython>=7.7.0 ipdb>=0.12 -# for previewing the README.rst -docutils>=0.14 # testing tools pylint>=2.3.1 diff --git a/setup.cfg b/setup.cfg index 7dab315a..ac735909 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] license_file = LICENSE -description-file = README.rst +description-file = README.md [flake8] exclude = diff --git a/setup.py b/setup.py index c1777461..5ad623f7 100644 --- a/setup.py +++ b/setup.py @@ -25,7 +25,8 @@ def find_version(*file_paths): name="cloudformation-cli", version=find_version("src", "rpdk", "core", "__init__.py"), description=__doc__, - long_description=read("README.rst"), + long_description=read("README.md"), + long_description_content_type="text/markdown", author="Amazon Web Services", author_email="aws-cloudformation-developers@amazon.com", url="https://github.com/aws-cloudformation/aws-cloudformation-rpdk/", @@ -52,7 +53,7 @@ def find_version(*file_paths): }, license="Apache License 2.0", classifiers=[ - "Development Status :: 4 - Beta", + "Development Status :: 5 - Production/Stable", "Environment :: Console", "Intended Audience :: Developers", "License :: OSI Approved :: Apache Software License",