Merge pull request #1754 from jaredgrubb/jgrubb-doc

Docs: fix some Sphinx warnings

master/docs/developer/py3-compat.rst

@@ -10,12 +10,16 @@ Imports
 All ``__future__`` import have to happen at the top of the module, anything else is seen as a syntax error.
 All imports from the python-future package should happen below ``__future__`` imports, but before any other.
 
-Yes::
+Yes:
+
+.. code-block:: python
 
     from __future__ import print_function
     from builtins import basestring
 
-No::
+No:
+
+.. code-block:: python
 
     from twisted.application import internet
     from twisted.spread import pb
@@ -28,13 +32,17 @@ In python3, ``dict.iteritems`` is no longer available.
 While ``dict.items()`` does exist, it can be memory intensive in python2.
 For this reason, please use the python.future function ``iteritems()``.
 
-Example::
+Example:
+
+.. code-block:: python
 
     d = {"cheese": 4, "bread": 5, "milk": 1}
     for item, num in d.iteritems():
         print("We have {} {}".format(num, item))
 
-should be written as::
+should be written as:
+
+.. code-block:: python
 
     from future.utils import iteritems
     d = {"cheese": 4, "bread": 5, "milk": 1}
@@ -47,13 +55,17 @@ If a list is required, please use ``list(iteritems(dict))``.
 This is for compatibility with the six library.
 
 For iterating over dictionary keys, please use ``for key in dict:``.
-For example::
+For example:
+
+.. code-block:: python
 
     d = {"cheese": 4, "bread": 5, "milk": 1}
     for item in d:
         print("We have {}".format(item))
 
-Similarly when you want a list of keys::
+Similarly when you want a list of keys:
+
+.. code-block:: python
 
     keys = list(d)
 
@@ -62,13 +74,17 @@ New-style classes
 All classes in Python3 are newstyle, so any classes added to the code base must therefore be new-style.
 This is done by inheriting ``object``
 
-Old-style::
+Old-style:
+
+.. code-block:: python
 
     class Foo:
         def __init__(self, bar)
             self.bar = bar
 
-new-style::
+new-style:
+
+.. code-block:: python
 
     class Foo(object):
         def __init__(self, bar)
@@ -89,7 +105,9 @@ It can be both unicode and bytestring.
 In python3, this is no longer the case.
 For this reasons all string must be marked with either ``u''`` or ``b''`` to signify if the string is a unicode string or a bytestring respectively
 
-Example::
+Example:
+
+.. code-block:: python
 
     u'this is a unicode string, a string for humans to read'
     b'This is a bytestring, a string for computers to read'
@@ -98,14 +116,18 @@ Example::
 Exceptions
 ----------
 All exceptions should be written with the ``as`` statement.
-Before::
+Before:
+
+.. code-block:: python
 
     try:
         number = 5 / 0
     except ZeroDivisionError, err:
         print(err.msg)
 
-After::
+After:
+
+.. code-block:: python
 
     try:
         number = 5/0
@@ -119,13 +141,17 @@ In Python2 there is a basestring type, which both str and unicode inherit.
 In Python3, only unicode should be of this type, while bytestrings are ``type(byte)``.
 
 For this reason, we use a builtin form python future.
-Before::
+Before:
+
+.. code-block:: python
 
     s = "this is a string"
     if(isinstance(basestring)):
         print "This line will run"
 
-After::
+After:
+
+.. code-block:: python
 
     from builtins import str
     unicode_s = u"this is a unicode string"
@@ -147,11 +173,15 @@ Division
 Integer division is slightly different in Python3.
 ``//`` is integer division and ``/`` is floating point division.
 For this reason, we use ``division`` from the future module.
-Before::
+Before:
+
+.. code-block:: python
 
     2 / 3 = 0
 
-After::
+After:
+
+.. code-block:: python
 
     from __future__ import division
 

master/docs/manual/cfg-dbconfig.rst

@@ -11,7 +11,9 @@ DbConfig can get and store any jsonable object to the db for use by other master
 The design is voluntary simplistic, the focus is on the easy use rather than efficiency.
 A separate db connection is created each time get() or set() is called.
 
-Example ::
+Example:
+
+.. code-block:: python
 
     from buildbot.plugins import util, buildslave
     c = BuildmasterConfig = {}

master/docs/manual/cfg-www.rst

@@ -480,7 +480,9 @@ You can grant roles from groups information provided by the Auth plugins, or if
 Example Configs
 +++++++++++++++
 
-Simple config which allows admin people to run everything::
+Simple config which allows admin people to run everything:
+
+.. code-block:: python
 
     from buildbot.plugins import *
     authz = util.Authz(
@@ -496,7 +498,9 @@ Simple config which allows admin people to run everything::
     c['www']['auth'] = auth
     c['www']['authz'] = authz
 
-More complex config with separation per branch::
+More complex config with separation per branch:
+
+.. code-block:: python
 
     from buildbot.plugins import *
 

master/docs/manual/cfg-wwwhooks.rst

@@ -9,7 +9,9 @@ Implementations (such as a trivial json-based endpoint and a GitHub implementati
 The format of the url is :samp:`/change_hook/{DIALECT}` where DIALECT is a package within the hooks directory.
 Change_hook is disabled by default and each DIALECT has to be enabled separately, for security reasons
 
-An example www configuration line which enables change_hook and two DIALECTS::
+An example www configuration line which enables change_hook and two DIALECTS:
+
+.. code-block:: python
 
     c['www'] = dict(
         change_hook_dialects={
@@ -77,17 +79,19 @@ The parameters are:
 
 :guilabel:`Secret`
     Any value.
-    If you provide a non-empty value (recommended), make sure that your hook is configured to use it::
-
-        c['www'] = dict(
-            ...,
-            change_hook_dialects={
-                'github': {
-                    'secret': 'MY-SECRET',
-                    'strict': True
-                }
-            },
-            ...))
+    If you provide a non-empty value (recommended), make sure that your hook is configured to use it:
+
+    .. code-block:: python
+
+            c['www'] = dict(
+                ...,
+                change_hook_dialects={
+                    'github': {
+                        'secret': 'MY-SECRET',
+                        'strict': True
+                    }
+                },
+                ...))
 
 :guilabel:`Which events would you like to trigger this webhook?`
     Leave the default -- ``Just the push event`` -- other kind of events are not currently supported.
@@ -99,7 +103,9 @@ And then press the ``Add Webhook`` button.
     The incoming HTTP requests for this hook are not authenticated by default.
     Anyone who can access the web server can "fake" a request from GitHub, potentially causing the buildmaster to run arbitrary code.
 
-To protect URL against unauthorized access you either specify a secret, or you should use ``change_hook_auth`` option::
+To protect URL against unauthorized access you either specify a secret, or you should use ``change_hook_auth`` option:
+
+.. code-block:: python
 
     c['www'] = dict(...,
           change_hook_auth=["file:changehook.passwd"]))
@@ -123,7 +129,7 @@ BitBucket hook
 
 The BitBucket hook is as simple as GitHub one and it also takes no options.
 
-::
+.. code-block:: python
 
     c['www'] = dict(...,
         change_hook_dialects={ 'bitbucket' : True }))
@@ -142,7 +148,7 @@ This script may be useful in cases where you cannot expose the WebStatus for pub
 
 To protect URL against unauthorized access you should use ``change_hook_auth`` option.
 
-::
+.. code-block:: python
 
   c['www'] = dict(...,
         change_hook_auth=["file:changehook.passwd"]))
@@ -234,7 +240,7 @@ These parameters will be passed along to the scheduler.
 
 To protect URL against unauthorized access you should use ``change_hook_auth`` option.
 
-::
+.. code-block:: python
 
     c['www'] = dict(...,
         change_hook_auth=["file:changehook.passwd"]
@@ -265,7 +271,7 @@ For example, it the grid URL is ``http://builds.example.com/bbot/grid``, then po
 
 To protect URL against unauthorized access you should use ``change_hook_auth`` option.
 
-::
+.. code-block:: python
 
     c['www'] = dict(...,
         change_hook_auth=["file:changehook.passwd"]

master/docs/relnotes/index.rst

@@ -50,7 +50,7 @@ For a more detailed description of the changes made in this version, see the git
 
 .. code-block:: bash
 
-   git log v0.8.9..eight
+   git log v0.8.10..master
 
 Older Versions
 --------------