Difference between revisions of "Designate/Development/StyleGuide"
< Designate | Development
(→Designate Style Guide) |
(→Designate Style Guide) |
||
Line 6: | Line 6: | ||
Start new files with the following. Replace where needed: | Start new files with the following. Replace where needed: | ||
− | + | <source lang="python" collapse="true"> | |
− | < | ||
# -*- coding: utf-8 -*- | # -*- coding: utf-8 -*- | ||
# Copyright <year> <company> | # Copyright <year> <company> | ||
Line 31: | Line 30: | ||
Specs: <Link to the spec document | Specs: <Link to the spec document | ||
""" | """ | ||
− | </ | + | </source> |
Use the Sphinx markup. Here is an example: | Use the Sphinx markup. Here is an example: | ||
− | < | + | <source lang="python" collapse="true"> |
class MyClass(object): | class MyClass(object): | ||
"""<description> | """<description> | ||
Line 57: | Line 56: | ||
.. warning:: <use sparingly> | .. warning:: <use sparingly> | ||
""" | """ | ||
− | </ | + | </source> |
Revision as of 13:37, 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>
"""