Documentação¶

Largura da linha¶

As linhas devem ter no máximo 80 colunas. A unica exeção são urls longas e trechos de códigos.

Títulos e Seções¶

Títulos e seções são criados adicionado os caracteres de pontuação na linha abaixo do título do mesmo tamanho do texto.

• # Usado para indicar título da página.

• = Usado para indicar seções na página.

• - Usado para subseções.

• ~ Usado para sub-subseções

• ^ Usado para sub-sub-subseções.

Títulos não devem ser adicionados mais do que 5 níveis de profundidade. Títulos devem ser precedido e seguido por uma linha em branco.

Parágrafo¶

Parágrafos são blocos de texto simples, com todas as linhas no mesmo nível de indentação. Parágrafos devem ser separados por uma ou mais linhas em branco.

Marcações¶

• Um asterisco: text para ênfase (itálico),

• Dois asteriscos: text para dar ênfase forte (negrito), e

• crases: text para exemplos de código.

Se asteriscos ou crases devem aparecer no texto elas devem ser precidadas por uma barra invertida (\) para serem escapadas.

Restrições para a marcação:

• As marcações Não podem ser aninhadas.

• O conteúdo não pode iniciar ou terminar com espaço em branco: * text* está incorreto.

• O conteúdo deve ser separado do restante do texto por non-word characters. Use uma barra invertida escapando um espaço para corrigir isso: onelong\ *bolded*\ word.

Listas¶

A marcação de listas é muito paracido com markdown. Listas não ordenadas começam a linha com um asterisco seguido de um espaço. Listas númericas podem ser criadas com os números na frente ou # para númerar automaticamente:

* Isso é uma linha
* Essa também.
  Mas tem duas linhas


1. Primeira linha
2. Segunda linha

#. Númeração automatica
#. Vai salvar seu tempo.

Listas indentadas também podem ser criadas, indentando as seções e separando elas por uma linha em branco:

* Primeira linha
* Segunda linha

    * Indo mais um nível
    * Wow!

* De volta para o primeiro nível.

Listas de definição pode ser criadas da seguinte forma:

termo
    definição
CakePHP
    Framework MVC para PHP

Os termos não podem ter mais do que uma linha, mas as definições podem ter muitas linhas e todos as linhas devem ter um indentação consistente.

Links¶

Existe vários tipos de links, cada um com seu objetivo de uso.

`Link Externo <http://example.com>`_

Descrevendo classes e seus conteúdos¶

A documentação do CakePHP utiliza o phpdomain que fornece algumas diretivas para descrever objetos e construtores. Usar essas diretivas é essêncial para criar índices e referências em toda a documentação.

Descrevendo Classes e Construtores¶

Cada diretiva alimenta o índice e/ou o namespace do índice.

.. php:global:: name¶

Essa diretiva declara uma variável global.

.. php:function:: name(signature)¶

Define um função global fora da classe.

.. php:const:: name¶

Essa diretiva declara uma constante, você também pode usar dentro de uma classe para declarar uma constante da classe.

.. php:exception:: name¶

Essa diretiva declara um nova Exception no namespace atual. A declaração pode conter os argumentos do construtor.

.. php:class:: name¶

Descreve uma classe. Métodos, atributos e constantes que pertence a classe devem ser declaradas dentro dessa diretiva:

.. php:class:: MyClass

    Class description

   .. php:method:: method($argument)

   Method description

Atributos, métodos e constante não precisam estar um nível abaixo. Podem ser declaradas no mesmo nível da classe:

.. php:class:: MyClass

    Text about the class

.. php:method:: methodName()

    Text about the method

Ver também

php:method, php:attr, php:const

.. php:method:: name(signature)¶

Descreve um método da classe, seus argumentos, valor retornado e exceptions:

.. php:method:: instanceMethod($one, $two)

    :param string $one: Primeiro parâmetro.
    :param string $two: Segundo parâmetro.
    :returns: Um array com várias coisas.
    :throws: InvalidArgumentException

   Isso é um método de instância.

.. php:staticmethod:: ClassName::methodName(signature)¶

Descreve um método estático, seus argumentos, valor retornado e exceptions veja php:method para mais detalhes.

.. php:attr:: name¶

Descreve um propriedade/atributo de uma classe.

.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
    :noindex:

Código Fonte¶

Blocos de códigos literais são criados terminando um paragrafo com ::. O bloco deve ser indentado e como todos os parágrafos ser separados por uma linha:

Isso é um parágrafo::

    while ($i--) {
        doStuff()
    }

Isso é um resto normal denovo.

Textos literais não são modificados ou formatados, salvo quando o level de indentação é removido.

Notas e Avisos¶

As vezes você quer infomar ao leitor do manual um dica importante, um lembrete ou um aviso importante. Admonitions no sphinx são usados para isso. Existe três tipos de admonitions.

• .. tip:: Tips são usandos no documento para salientar algo importante. O conteúdo deve ter as sentenças corretas e pontuação apropriada.

• .. note:: Notes são usadas para especificar uma parte importante da informação. O conteúdo deve ter as sentenças corretas e pontuação apropriada.

• .. warning:: Warnings são usados para informar potenciais obstáculos ou informações sobre segurança. O conteúdo deve ter as sentenças corretas e pontuação apropriada.

Todos os admonitions são declarados da mesma forma:

.. note::

    Indentado e precedido por uma linha branca. Como uma parágrafo.

Esse texto não pertence a nota.