Existem algumas convenções comuns para o conteúdo e formatação de cadeias de documentação.
A primeira linha deve ser sempre um resumo curto e conciso do propósito do objeto. Por uma questão de brevidade, não deve declarar explicitamente o nome ou o tipo do objeto, uma vez que estes estão disponíveis por outros meios (exceto se o nome for um verbo descrevendo a operação de uma função). Essa linha deve começar com uma letra maiúscula e terminar com um período.
Se houver mais linhas na seqüência de documentação, a segunda linha deverá estar em branco, separando visualmente o resumo do resto da descrição. As linhas a seguir devem ser um ou mais parágrafos descrevendo as convenções de chamada do objeto, seus efeitos colaterais, etc.
O analisador Python não tira a indentação de literais de seqüência de caracteres de várias linhas no Python, portanto, as ferramentas que processam a documentação precisam remover a indentação, se desejado. Isso é feito usando a seguinte convenção. A primeira linha não em branco após a primeira linha da cadeia determina a quantidade de recuo para toda a cadeia de documentação. (Não podemos usar a primeira linha, pois ela é geralmente adjacente às aspas de abertura da string, portanto, seu recuo não é aparente na string literal). Espaços em branco “equivalentes” a essa indentação são removidos do início de todas as linhas da string . Linhas que são recuadas menos não devem ocorrer, mas se ocorrerem, todos os espaços em branco iniciais deverão ser removidos. A equivalência de espaço em branco deve ser testada após a expansão das guias (para 8 espaços, normalmente).
Aqui está um exemplo de uma docstring de várias linhas:
>>> def my_function(): ... """Do nothing, but document it. ... ... No, really, it doesn't do anything. ... """ ... pass ... >>> print my_function.__doc__ Do nothing, but document it. No, really, it doesn't do anything.