Merge lp:~rvb/maas/api-doc-bug-1411363 into lp:~maas-committers/maas/trunk

[Raphaël Badin]

Add a test to make sure the API documentation contains some of the text used in the docstrings of the API methods.

This is meant to catch bugs like bug 1411363 where the API documentation gets broken before the API doc gets deployed.

[Gavin Panella (allenap)]

Cool. There may be some surprises when those particular doc strings are changed and this test fails, but I think it's all for a good cause.

review: Approve

[Raphaël Badin (rvb)]

> Cool. There may be some surprises when those particular doc strings are
> changed and this test fails, but I think it's all for a good cause.

Yeah, these failures will be easy to fix.

=== modified file 'src/maasserver/api/tests/test_doc.py'
--- src/maasserver/api/tests/test_doc.py	2014-09-27 16:01:00 +0000
+++ src/maasserver/api/tests/test_doc.py	2015-01-16 10:16:22 +0000
@@ -33,6 +33,7 @@
     generate_api_docs,
     generate_power_types_doc,
     )
+from maasserver.api.doc_handler import render_api_docs
 from maasserver.api.support import (
     operation,
     OperationsHandler,
@@ -185,6 +186,21 @@
             "%d handlers are missing an api_doc_section_name field." % len(
                 handlers_missing_section_name))
 
+    def test_contains_documentation_from_handlers(self):
+        # The documentation contains some of the text used in the docstrings
+        # of the API's methods.
+        # This test is meant to catch bugs like bug 1411363.
+        doc = render_api_docs()
+        doc_snippets = [
+            # Doc for a method.
+            "Manage custom commissioning scripts.",
+            # Doc for a method parameter.
+            "GET a FileStorage object as a json object.",
+            # Doc for a method parameter (:param: doc).
+            "Optional prefix used to filter out the returned files.",
+        ]
+        self.assertThat(doc, ContainsAll(doc_snippets))
+
 
 class ExampleHandler(OperationsHandler):
     """An example handler."""