Difference between revisions of "Designate/Development/StyleGuide"
< Designate | Development
(→Designate Style Guide) |
(→Designate Style Guide) |
||
Line 28: | Line 28: | ||
~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~ | ||
<Describe what the module should do, especially interactions with other components> | <Describe what the module should do, especially interactions with other components> | ||
− | Specs: <Link to the spec document | + | Specs: <Link to the spec document> |
""" | """ | ||
</source> | </source> |
Revision as of 13:39, 4 January 2016
Designate Style Guide
This guide is unofficial at the moment
Follow OpenStack Style Guidelines and the Pocoo Style Guide
Start new files with the following. Replace where needed:
# -*- coding: utf-8 -*-
# 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>
Specs: <Link to the spec document>
"""
Use the Sphinx markup. Here is an example:
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>
"""