Add documentation about using the badge

The website has added a badge people can use on their project pages. Add
some documentation about it.

Depends-On: https://review.openstack.org/568975
Change-Id: I97911f68d60f8be25f2eba66ccd8aeb9b1f34c49

doc/source/conf.py

@@ -39,6 +39,9 @@ extensions = [
 #extensions = ['sphinx.ext.intersphinx']
 #intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
 
+# The docs build references a non-local image served at zuul-ci.org.
+suppress_warnings = ['image.nonlocal_uri']
+
 primary_domain = 'zuuldoc'
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/user/badges.rst

@@ -0,0 +1,18 @@
+:title: Badges
+
+.. We don't need no stinking badges
+
+.. _badges:
+
+Badges
+======
+
+You can embed a badge declaring that your project is gated and therefore by
+definition always has a working build. Since there is only one status to
+report, it is a simple static file:
+
+.. image:: https://zuul-ci.org/gated.svg
+   :alt: Zuul: Gated
+
+To use it, simply put ``https://zuul-ci.org/gated.svg`` into an RST or
+markdown formatted README file, or use it in an ``<img>`` tag in HTML.

doc/source/user/index.rst

@@ -16,3 +16,4 @@ configure it to meet your needs.
    config
    jobs
    encryption
+   badges