Add a style guide

Change-Id: Id4a03408eb17c6284a7975184df25c8fa080eada

doc/source/developer-guidelines.rst

@@ -2,6 +2,7 @@
 Developer Guidelines
 ********************
 
+
 Example DNS Names and IP Space
 ==============================
 
@@ -40,7 +41,109 @@ Several common reserved IP blocks:
 * 198.51.100.0/24
 * 203.0.113.0/24
 * 2001:db8::/32
-  
+
 .. _IANA Special Use Domain Names: http://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml
 .. _IANA IPv4 Special Registry: http://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml
 .. _IANA IPv6 Special Registry: http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml
+
+Style Guide
+===========
+
+Follow `OpenStack Style Guidelines <http://docs.openstack.org/developer/hacking/>`_
+
+File header
+-----------
+
+Start new files with the following. Replace where needed:
+
+.. code-block:: python
+
+    # Copyright <year> <company>
+    #
+    # Author: <name> <email addr>
+    #
+    # Licensed under the Apache License, Version 2.0 (the "License"); you may
+    # not use this file except in compliance with the License. You may obtain
+    # a copy of the License at
+    #
+    #      http://www.apache.org/licenses/LICENSE-2.0
+    #
+    # Unless required by applicable law or agreed to in writing, software
+    # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+    # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    # License for the specific language governing permissions and limitations
+    # under the License.
+
+    """
+    <package.module>
+    ~~~~~~~~~~~~~~
+    <Describe what the module should do, especially interactions with
+    other components and caveats>
+
+    <Optional links>
+    `Specs: Refer to to a spec document if relevant`_
+
+    `User documentation <FILL_THIS.html>`_ <Refer to files under doc/>
+    <This is useful to remind developers to keep the docs up to date>
+    """
+
+Example:
+
+.. code-block:: rst
+
+    backend.impl_akamai
+    ~~~~~~~~~~~~~~~~~~~
+    Akamai backend. Create and delete zones on Akamai. Blah Blah...
+
+    `Specs: Keystone Session <https://github.com/openstack/designate-specs/blob/master/specs/kilo/switch-to-keystone-session.rst>`_
+
+    `User documentation <backend.html>`_
+
+When updating a module, please ensure that the related user documentation is updated as well.
+
+Docstrings
+----------
+
+Use the Sphinx markup. Here is an example:
+
+.. code-block:: python
+
+    class MyClass(object):
+        """<description>
+        mention a function :func:`foo` or a class :class:`Bar`
+        """
+
+        def function(self, foo):
+            """<describe what the function does>
+            :param foo: <description>
+            :type foo: <type>
+            :returns: <describe the returned value>
+            :rtype: <returned type>
+            :raises: <list raised exceptions>
+
+            :Example:
+
+            >>> a = b - c
+            >>> <more Python code>
+
+            .. note:: <add a note here>
+            .. seealso:: <blah>
+            .. warning:: <use sparingly>
+            """
+
+Logging
+-------
+
+See http://docs.openstack.org/developer/oslo.i18n/guidelines.html
+
+.. code-block:: python
+
+    # Do not use "%" string formatting
+    # No localization for debug
+    LOG.debug("... %s", variable)
+    LOG.info(_LI("... %s..."), variable)
+    # Use named interpolation when more than one replacement is done
+    LOG.info(_LI("... %(key)s ..."), {'key': 'value', ...})
+    LOG.warn(_LW("... %(key)s"), {'key': 'value'})
+    LOG.error(_LE("... %(key)s"), {'key': 'value'})
+    LOG.critical(_LC("... %(key)s"), {'key': 'value'})