docs - clean up doc build (#754)

* Build docs during CI to catch out errors * Treat warnings as errors * Fix doc warning/errors This adds the API reference docs to the site navigation, so we can start to see just how bad they are. :)
cloud-custodian · Dec 21, 2016 · 24bdc7a · 24bdc7a
1 parent e3522c0
commit 24bdc7a
Show file tree

Hide file tree

Showing 10 changed files with 24 additions and 19 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -10,9 +10,6 @@ install:
   - pip install -r requirements-dev.txt
   - pip install coveralls
   - python setup.py develop
-script: nosetests -s -v --with-coverage --cover-package=c7n tests
+script: make sphinx && nosetests -s -v --with-coverage --cover-package=c7n tests
 after_success:
   coveralls
-
-
-
diff --git a/c7n/actions.py b/c7n/actions.py
@@ -311,14 +311,16 @@ def send_sqs(self, message):
 class AutoTagUser(EventAction):
     """Tag a resource with the user who created/modified it.
 
-    policies:
-      - name: ec2-auto-tag-owner
-        resource: ec2
-        filters:
-         - tag:Owner: absent
-        actions:
-         - type: auto-tag-creator
-           tag: OwnerContact
+    .. code-block:: yaml
+
+      policies:
+        - name: ec2-auto-tag-owner
+          resource: ec2
+          filters:
+           - tag:Owner: absent
+          actions:
+           - type: auto-tag-creator
+             tag: OwnerContact
 
     There's a number of caveats to usage, resources which don't
     include tagging as part of their api, may have some delay before

diff --git a/c7n/filters/metrics.py b/c7n/filters/metrics.py
@@ -31,7 +31,7 @@ class MetricsFilter(Filter):
     - GetMetricStatistics - http://goo.gl/w8mMEY
     - Supported Metrics - http://goo.gl/n0E0L7
 
-    usage:: yaml
+    .. code-block:: yaml
 
       - name: ec2-underutilized
         resource: ec2

diff --git a/c7n/resources/ebs.py b/c7n/resources/ebs.py
@@ -497,8 +497,7 @@ class EncryptInstanceVolumes(BaseAction):
     - Requires instance restart
     - Not suitable for autoscale groups.
 
-    Multistep process
-    -----------------
+    Multistep process:
 
     - Stop instance (if running)
     - For each volume
@@ -517,7 +516,7 @@ class EncryptInstanceVolumes(BaseAction):
 
     :example:
 
-        .. code-base: yaml
+        .. code-block:: yaml
 
             policies:
               - name: encrypt-unencrypted-ebs

diff --git a/c7n/utils.py b/c7n/utils.py
@@ -89,7 +89,7 @@ def type_schema(
                  inherits issues with additionalProperties and type enums.
      - aliases: additional names this type maybe called
      - required: list of required properties, by default 'type' is required
-     - **props: additional key value properties
+     - props: additional key value properties
     """
     if aliases:
         type_names = [type_name]

diff --git a/docs/Makefile.sphinx b/docs/Makefile.sphinx
@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SRCDIR        = docs/source
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = $(SRCDIR)/../build

diff --git a/docs/source/_static/c1_labs.png b/docs/source/_static/c1_labs.png
diff --git a/docs/source/c1_labs.ico b/docs/source/c1_labs.ico
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -137,7 +137,7 @@
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = 'c1_labs.png'
+html_favicon = 'c1_labs.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -50,6 +50,13 @@ Navigate below and get started with Cloud Custodian!
    developer   
 
 
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+
+   generated/modules
+
+
 Indices and tables
 ==================