Getting Started#

If you have not already done so, create or activate a virtualenv. Unless otherwise stated, assume all terminal code below is executed within the virtualenv.

Install the requirements#

This will also install the Code Annotations package as editable, to allow access to the Stevedore plugins.

$ make requirements

Run the tests#

Make sure everything is working okay:

$ make test


$ tox


$ tox -e py27

Create a configuration file#

Configuration for code-annotations is done via a yaml file, The default filename of which is .annotations. The following is an example of a minimal configuration file. See .annotations_sample for a more thorough example and Configuration for more details. In this example the Code Annotations tools will search for the string .. annotation_token: in the comments of Python and Javascript files using the built-in extensions.

# Path that you wish to static search, can be passed on the command line
# Directories will be searched recursively, but this can also point to a single file
source_path: ./

# Directory to write the report to, can be passed on the command line
report_path: reports

# Path to the Django annotation safelist file
safelist_path: .annotation_safe_list.yml

# Percentage of Django models which must have annotations in order to pass coverage checking
coverage_target: 50.0

# Definitions of the annotations to search for. Notice the trailing colon, this is a mapping type!
# For more information see "Writing Annotations"
    ".. annotation_token:":

# Code Annotations extensions to load and the file extensions to map them to
        - py

Create some annotations#

In your source_path add some comments with annotations in them. Examples:


.. annotation_token: This comment text will be captured along with the token in our search.

# .. annotation_token: This comment will also be captured.


.. annotation_token: So will this.

// .. annotation_token: And this!

Add more structure to your annotations#

Annotations can be more than simple messages. They can enforce the use of choices from a fixed list, and can be grouped to provide more context-aware information. See Configuration and Writing Annotations for more information on how to use those options.