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.