Contributing Topics and Examples to the AWS CLI

Setting a development environment

If you have not cloned the CLI repository and set up a development environment, follow these steps.

First, clone the AWS CLI git repository:

~$ git clone git@github.com:aws/aws-cli.git

Then use pip to install the CLI:

~$ cd aws-cli
~/aws-cli$ pip install -e .

You are now ready to start contributing to the CLI.

Step 1: Create a file in the topics dirctory

Navigate from the root directory of the CLI’s cloned git repository to the topics directory:

~/aws-cli$ cd awscli/topics

Use a text editor to create a new file:

~/aws-cli/topics$ vim my-sample-topic.rst

The reStructuredText file, my-sample-topic.rst, will show up in the output of the aws help topics command as my-sample-topic. To access the topic’s contents, a user should run the command aws help my-sample-topic.

Step 2: Add the appropriate fields to the topic

You will need to add some metadata to the beginning of the file in the form of reStructuredText fields to the beginning of the file. These fields play an important role in the display and organization of each topic.

The currently supported fields are:

• title: Specifies a title for the topic. Its value will be displayed as the title whenever the content of the topic is displayed through the command aws help my-sample-topic.
• description: Specifies a sentence description for the topic. Its value will be displayed when listing all of the available topics through the command aws help topics.
• category: Specifies a category to which a topic belongs to. . A topic can belong to one category only.. The topic will be listed under the specified category when viewing the available topics through the command aws help topics.

Here is an example of what the list of fields would look like:

:title: My Sample Topic
:description: This describes my sample topic
:category: General

Step 3: Add the content

After these fields have been added to the top of the file, you can now add some reStructuredText content.

:title: My Sample Topic
:description: This describes my sample topic
:category: General

Here is a summary of my topic.


My Section
==========
Here is some more content.


My Subsection
-------------
Here is even more content.

The content and the structure of the content I added is arbitrary. As long as it is valid reStructuredText, decide for yourself what you want to add and how you want to structure it.

Step 4: Regenerate the topic index

After you have written the content, run the script make-topic-index to make sure the topic will be visible in the aws help topics command and available through the aws topics my-sample-topic command. This step is straightforward as well. All you need to do is run the script make-topic-index:

~/aws-cli/topics$ cd ~/aws-cli/scripts
~/aws-cli/scripts$ ./make-topic-index

This script will run through all of the topic files in awscli/topics and regenerate an index that allows for fast lookups of topics in the CLI. You can use the aws help topics command to check that your topic is available. (The following shows only the AVAILABLE TOPICS section of the output.)

$ aws help topics

AVAILABLE TOPICS
   General
       o config-vars: Configuration Variables for the AWS CLI

       o my-sample-topic: This describes my sample topic

       o return-codes: Describes the various return codes of the AWS CLI

   S3
       o s3-config: Advanced configuration for AWS S3 Commands

And the content of the topic is available through the aws help my-sample-topic command:

$ aws help my-sample-topic


NAME
       My Sample Topic -

       Here is a summary of my topic.

MY SECTION
       Here is some more content.

   My Subsection
       Here is even more content.

How do I write an example?

By example, I mean the EXAMPLES section that appears in the output when you run the help command for a CLI command. For example, take the help output for aws ec2 describe-instances:

$ aws ec2 describe-instances help

...continued...
EXAMPLES
       To describe an Amazon EC2 instance

       Command:

          aws ec2 describe-instances --instance-ids i-5203422c

       To describe all instances with the instance type m1.small

       Command:

          aws ec2 describe-instances --filters "Name=instance-type,Values=m1.small"

       To describe all instances with a Owner tag

       Command:

          aws ec2 describe-instances --filters "Name=tag-key,Values=Owner"

       To describe all instances with a Purpose=test tag

       Command:

          aws ec2 describe-instances --filters "Name=tag:Purpose,Values=test"
...continued...

All of these examples are written in reStructuredText and are located in the example section of the CLI codebase.

Writing an example for a command requires even fewer steps than writing a topic. In this walkthrough, we will add an example for aws iot list-things.

If you have not already done so, make sure you have set up your development environment as described earlier in this post.

Step 1: Create a file in the examples dirctory

Navigate from the root directory of the CLI’s cloned git repository to the examples directory:

~/aws-cli$ cd awscli/examples

This directory contains directories of other service commands in the CLI. For this walkthrough, you need to navigate to the iot directory (or create it if it does not exist):

~/aws-cli/examples$ cd iot

Use a text editor to create a new file:

~/aws-cli/examples/iot$ vim list-things.rst

In order for the example to be picked up in the aws iot list-things help command, the name of the file must match the name of the command.

Step 2: Add the content

Now just add reStructuredText content to this newly created file:

The following command lists all AWS IoT things::

$ aws iot list-things

Output::

    {
        "things": []
    }

To confirm the example was added to the help command:

$ aws iot list-things help

...continued...
EXAMPLES
       The following command lists all AWS IoT things:

          $ aws iot list-things

       Output:

          {
              "things": []
          }
...continued...