Difference between revisions of "Designate/Development/StyleGuide"
< Designate | Development
(→Designate Style Guide) |
(→Designate Style Guide) |
||
| Line 31: | Line 31: | ||
Specs: <Link to the spec document | Specs: <Link to the spec document | ||
""" | """ | ||
| + | </pre> | ||
| + | |||
| + | Use the Sphinx markup. Here is an example: | ||
| + | <pre> | ||
| + | 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> | ||
| + | """ | ||
</pre> | </pre> | ||
Revision as of 13:32, 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>
"""
