Merge "clean up api_samples documentation"

1 files changed, 14 insertions, 4 deletions

diff --git a/nova/tests/integrated/api_samples/README.rst b/nova/tests/integrated/api_samples/README.rst
index 065df1d32..b2ad71d4c 100644
--- a/nova/tests/integrated/api_samples/README.rst
+++ b/nova/tests/integrated/api_samples/README.rst
@@ -1,11 +1,21 @@
 Api Samples
 ===========
 
-Samples in this directory are automatically generated from the api samples
-integration tests. To regenerate the samples, simply set GENERATE_SAMPLES
-in the environment before running the tests. For example:
+This part of the tree contains templates for API samples. The
+documentation in doc/api_samples is completely autogenerated from the
+tests in this directory.
+
+To add a new api sample, add tests for the common passing and failing
+cases in this directory for your extension, and modify test_samples.py
+for your tests. There should be both JSON and XML tests included.
+
+Then run the following command:
 
   GENERATE_SAMPLES=True tox -epy27 nova.tests.integrated
 
+Which will create the files on doc/api_samples.
+
 If new tests are added or the .tpl files are changed due to bug fixes, the
-samples should be regenerated so they are in sync with the templates.
+samples must be regenerated so they are in sync with the templates, as
+there is an additional test which reloads the documentation and
+ensures that it's in sync.