+
+ Docstrings
+ +Documentação de funções/classes é feita com uma string + logo abaixo da declaração da mesma.
+ +
+>>> def func(a):
+>>> """Função mágica"""
+>>> return a
+
+>>> print func.__doc__
+Função mágica
+
+>>> help(func)
+ Sphinx
+ +Sphinx é o sistema de geração de documentação do Python.
+ +
+ PEP 257
+ +PEP 257 fala sobre formato de documentação de funções.
+PEP 257
+ +-
+
- Docstrings devem ter três aspas duplas. +
- Para classes, uma linha em branco antes e uma depois. +
- Para funções, sempre logo depois. +
- Se a documentação passar da coluna 80, as três + aspas que fecham a docstring devem ficar em uma + linha em separado. +
+class MyClass(object):
+
+ """This is my class. It is very long and I should break it
+ into several lines.
+ """
+
+ def __init__(self):
+ """Initialization."""
+ self.value = None
+ Sphinx Format
+ +O Sphinx tem um formato específico para documentação.
+ +-
+
- Parametros são documentados com
:param [nome]:
+ - Tipo do parametro é documetnado com
:type [tipo]:
+ - Retorno é marcado como
:return:
+ - Tipo de retorno é definido em
:rtype:
+ - Exceções podem ser descritas em
:raises [exceção]:
+
Sphinx Format (contd.)
+ +
+def send(sender, recipient, message_body, priority):
+ """Send a message to a recipient
+
+ :param str sender: The person sending the message
+ :param str recipient: The recipient of the message
+ :param str message_body: The body of the message
+ :param priority: The priority of the message, can be a number 1-5
+ :type priority: integer or None
+ :return: the message id
+ :rtype: int
+ :raises ValueError: if the message_body exceeds 160 characters
+ :raises TypeError: if the message_body is not a basestring
+ """
+ pass
+ (como gerar documentação Sphinx não será apresentado por + questões de espaço.)
+ +(mas é simples: um arquivo conf com os + diretórios a serem pesquisados e um makefile com a opção + html para geração de arquivos HTML.)
+