clean up api_samples documentation

the documentation for API samples was very misleading,
and hard to point people at what to do to add new samples.
Bring this more in line with reality.

Change-Id: I52da343d317cc77e5df30815f3f3721c2634585b

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.