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"
annotations:
    ".. annotation_token:":

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

Create some annotations#

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

Python

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

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

Javascript

/*
.. annotation_token: So will this.
*/

// .. annotation_token: And this!

Run an annotation search#

$ code_annotations static_find_annotations --config_file /path/to/your/config

If you have DJANGO_SETTINGS_MODULE correctly configured and have annotated some models you can also run a Django model annotation search:

$ code_annotations django_find_annotations --config_file /path/to/your/config

If all went well you should see a message telling you the name of the report file that was written out. Take a look in your favorite text editor to make sure all of your annotations were found. Different verbosity levels are available for this command, try -v, -vv, and -vvv to assist in debugging. --help will provide information on all of the available options.

By default the static annotation search will perform linting, which makes sure that any found annotations match the structure listed in configuration. If any issues are found the command will fail with no report written, otherwise a YAML file containing the results of the search will be written to your report_path. Both linting and reporting features can be turned off via command line flags.

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.

Get a human readable report#

The output generated by the search commands is a YAML file. To get a human readable report generated from one of those files in either rst or html format, you can use the generate_docs command.

There are several configuration options available for this command, including the ability to specify the output format, the output directory, and create links to the source files on sites like Github. For more information, see Configuration. Once your configuration is set, you can run:

$ code_annotations generate_docs --config_file /path/to/your/config /path/to/your/report.yaml

Which will generate files in the output directory you configured. From there you can open the files in your browser to see the report, if you chose HTML, or use a tool like restview to render the RST files to your browser.

Getting Started

Contents