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 -e py27
Create a configuration file#
Configuration for code-annotations is done via a yaml file, The default filename of which is
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
# 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#
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!
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
-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.