Documentação

Contribuir com a documentação é simples. Os arquivos estão hospedados em https://github.com/cakephp/docs. Sinta-se a vontade para copiar o repositório, adicionar suas alterações/melhorias/traduções e enviar um pull request. Você também pode editar a documentação online pelo Github, mesmo sem ter que fazer download dos arquivos – O botão “IMPROVE THIS DOC” presente na lateral direita em qualquer página vai direcioná-lo para o editor online do Github.

A documentação do CakePHP é continuamente integrada, sendo assim, você pode checar o status de várias builds no servidor Jenkins a qualquer momento.

Traduções

Envie um email para o time de documentação (docs at cakephp dot org) ou apareça no IRC (#cakephp na freenode) para discutir sobre qualquer área de tradução que você queira participar.

Nova tradução linguística

Nós queremos oferecer traduções completas tanto quanto possível, porém, podem haver momentos que um arquivo de tradução não está atualizado. Você deve sempre considerar a versão em inglês como a prevalecente.

Se o seu idioma não está dentre os listados, por favor nos contate pelo Github e nós vamos considerar incluí-lo. As seções a seguir são as primeiras que você deve considerar traduzir, pois seus arquivos não mudam frequentemente:

  • index.rst
  • intro.rst
  • quickstart.rst
  • installation.rst
  • /intro (todo o diretório)
  • /tutorials-and-examples (todo o diretório)

Lembrete para administradores de documentação

A estrutura de todos os diretórios de idioma devem espelhar a estrutura da matriz em inglês. Se a estrutura da documentação inglesa sofrer mudanças, as mesmas devem ser aplicadas em outros idiomas.

Por exemplo, se um novo arquivo é criado em en/file.rst, nós devemos:

  • Adicionar o arquivo a outros idiomas: pt/file.rst, fr/file.rst, etc

  • Deletar o conteúdo, mas manter as informações title, meta` e eventuais elementos ``toc-tree. A nota a seguir será adicionada até que alguém traduza o arquivo:

    File Title
    ##########
    
    .. note::
        Atualmente, a documentação desta página não é suportada em português.
    
        Por favor, sinta-se a vontade para nos enviar um *pull request* para o
        `Github <https://github.com/cakephp/docs>`_ ou use o botão
        **IMPROVE THIS DOC** para propor suas mudanças diretamente.
    
        Você pode consultar a versão em inglês deste tópico através do seletor de
        idiomas localizado ao lado direito do campo de buscas da documentação.
    
    // Se os elementos toc-tree existirem na versão inglesa
    .. toctree::
        :maxdepth: 1
    
        toc-file-x
        toc-file-y
        toc-file-z
    
    .. meta::
        :title lang=pt: Título do arquivo
        :keywords lang=pt: título, descrição,...
    

Dicas para tradutores

  • Navegue pelo idioma para o qual deseja traduzir a fim de certificar-se do que já foi traduzido.
  • Sinta-se a vontade para mergulhar na tradução caso o seu idioma já exista no manual.
  • Use Linguagem Informal.
  • Traduza o conteúdo e o título ao mesmo tempo.
  • Antes de submeter uma correção, compare à versão original. (se você corrigir algo, mas não indicar uma referência, sua submissão não será aceita).
  • Se você precisar escrever um termo em inglês, envolva-o na tag <em>. E.g. “asdf asdf Controller asdf” ou “asdf asdf Kontroller (Controller) asfd”, como for apropriado.
  • Não submeta traduções incompletas.
  • Não edite uma seção com alterações pendentes.
  • Não use Entidades HTML para caracteres acentuados, o manual usa UTF-8.
  • Não faça alterações significativas na marcação (HTML) ou adicione novo conteúdo.
  • Se estiver faltando alguma informação no conteúdo original, submeta uma correção paral tal antes de incluí-la em seu idioma.

Guia de formatação para documentação

A nova documentação do CakePHP é escrita com ReST. ReST (Re Structured Text) é uma sintaxe de marcação de texto simples, semelhante a markdown ou textfile. Para manter a consistência, recomenda-se que ao adicionar conteúdo à documentação do CakePHP, você siga as diretrizes aqui exemplificadas.

Comprimento da linha

Linhas de texto devem ser limitadas a 80 colunas. As únicas exceções devem ser URLs longas e trechos de código.

Títulos e Seções

Cabeçalhos de seção são criados ao sublinhar o título com caracteres de pontuação seguindo o comprimento do texto.

  • # é usado para títulos de páginas.
  • = é usado para seções de página.
  • - é usado para sub-seções de página.
  • ~ é usado para sub-sub-seções de página.
  • ^ é usado para sub-sub-sub-seções de página.

Os títulos não devem ser aninhados por mais de 5 níveis de profundidade. Os títulos devem ser precedidos e seguidos por uma linha em branco.

Parágrafos

Os parágrafos são simplesmente blocos de texto, com todas as linhas no mesmo nível de recuo. Os parágrafos devem ser separados por mais do que uma linha vazia.

Marcação em linha

  • Um asterisco: texto para dar ênfase (itálico) Vamos usá-lo para realce/ênfase.
    • *texto*.
  • Dois asteríscos: texto para ênfase forte (negrito) Vamos usá-lo para diretórios, títulos de listas, nomes de tabelas (excluindo a palavra “tabela”).
    • **/config/Migrations**, **articles**, etc.
  • Dois backquotes: texto para exemplos de código Vamos usá-lo para opções, nomes de colunas de tabelas, nomes de objetos (excluindo a palavra “objeto”) e nomes de métodos/funções – incluir “()”.
    • ``cascadeCallbacks``, ``true``, ``id``, ``PagesController``, ``config()``, etc.

Se asteríscos ou backquotes aparecerem em texto corrido e ficarem confusos com delimitadores de maração em linha, eles devem ser escapados com um backslash.

Marcação em linha tem algumas restrições:

  • Não deve estar aninhado.
  • O conteúdo não deve começar ou terminar com espaço: * texto* está errado.
  • O conteúdo deve estar separado de texto adjacente por caracteres non-word. Use um espaço escapado com uma contrabarra ao seu redor: umalonga\ *negrito*\ palavra.

Listas

A marcação de listas é muito parecida com o markdown. Listas desordenadas começam com um asterísco e um espaço. Listas enumeradas podem ser criadas tanto com números, ou # para auto numeração:

* Esse é um item
* Esse também, mas esse tem
  duas linhas.

1. Primeira linha
2. Segunda linha

#. Numeração automática
#. Vai lhe economizar algum tempo...

Listas com recuos também podem ser criadas ao recuar seções e separá-las com uma linha em branco:

* Primeira linha
* Segunda linha

    * Mais fundo
    * WOW!

* De volta ao primeiro nível...

Listas de definição podem ser criadas assim:

Termo
    Definição
CakePHP
    Um framework MVC para PHP

Termos não podem ultrapassar uma linha, porém definições podem e devem estar recuadas consistentemente.

Descrevendo classes e seus conteúdos

A documentação do CakePHP usa o phpdomain para fornecer directivas customizadas a fim de descrever objetos e construtores no PHP. Usar essas directivas e funções é um requisito para gerar a indexação adequada e recursos de referência cruzada.

Descrevendo classes e construtores

Cada directiva popula o índice, e/ou o índice do namespace.

.. php:global:: name

Esta directiva declara uma nova variável global PHP.

.. php:function:: name(signature)

Esta directiva define uma nova função global fora de uma classe.

.. php:const:: name

Esta directiva declara uma nova constante PHP, você também pode usá-lo aninhada dentro de uma directiva de classe para criar constantes de classe.

.. php:exception:: name

Esta directiva declara uma nova exceção no namespace atual. A assinatura pode incluir argumentos do construtor.

.. php:class:: name

Esta directiva descreve uma classe. Métodos, atributos, e as constantes pertencentes à classe devem estar dentro do corpo desta directiva:

    .. php:class:: MyClass

        Descrição da classe

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

       Descrição do método

Atributos, métodos e constantes não precisam estar aninhados. Eles podem
apenas seguir a declaração da classe::

    .. php:class:: MyClass

        Texto sobre a classe

    .. php:method:: methodName()

        Texto sobre o método

Ver também

php:method, php:attr, php:const

.. php:method:: name(signature)

Descreve um método de classe, seus argumentos, valor de retorno e exceções:

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

    :param string $one: O primeiro parâmetro.
    :param string $two: O segundo parâmetro.
    :returns: Um vetor de coisas.
    :throws: InvalidArgumentException

   Este é um método de instância
.. php:staticmethod:: ClassName::methodName(signature)

Descreve um método estático, seus argumentos, valor de retorno e exceções. Ver php:method para opções.

.. php:attr:: name

Descreve uma propriedade/atributo numa classe.

Prevenindo alertas do Sphinx

O Sphinx vai disparar alertas se uma função estiver referenciada em múltiplos arquivos. É um meio de garantir que você não adicionou uma função duas vezes, porém, algumas vezes você quer escrever a função em dois ou mais arquivos, e.g. debug object está referenciado em /development/debugging e em /core-libraries/global-constants-and-functions. Nesse caso, você pode adicionar :noindex: abaixo do debug da função para suprimir alertas. Mantenha apenas uma referência sem :no-index: para preservar a função referenciada:

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

Referenciamento cruzado

As funções a seguir se referem a objetos PHP e os links são gerados se uma directiva correspondente for encontrada:

:php:func:

Referencia uma função PHP.

:php:global:

Referencia uma variável global cujo nome possui o prefixo $.

:php:const:

Referencia tanto uma constante global como uma constante de classe. Constantes de classe devem ser precedidas pela classe mãe:

DateTime possui uma constante :php:const:`DateTime::ATOM`.
:php:class:

Referencia uma classe por nome:

:php:class:`ClassName`
:php:meth:

Referencia um método de uma classe. Essa função suporta ambos os métodos:

:php:meth:`DateTime::setDate`
:php:meth:`Classname::staticMethod`
:php:attr:

Referencia a propriedade de um objeto:

:php:attr:`ClassName::$propertyName`
:php:exc:

Referencia uma exceção.

Código-fonte

Blocos de código literais são criados ao finalizar um parágrafo com ::. O bloco de código literal deve estar recuado, e como todos os parágrafos, estar separado por linhas vazias:

Isto é um parágrafo::

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

Isto é texto novamente.

Texto literal não é modificado ou formatado, com exceção do primeiro nível de recuo que é removido.

Notas e alertas

Muitas vezes há momentos em que você deseja informar o leitor sobre uma dica importante, nota especial ou um perigo potencial. Admoestações no Sphinx são utilizados apenas para isto. Existem cinco tipos de advertências.

  • .. tip:: Dicas são usadas para documentar ou re-iterar informações importantes ou interessantes. O conteúdo da directiva deve ser escrito em sentenças completas e incluir a pontuação adequada.
  • .. note:: Notas são usadas para documentar uma peça importante de informação. O conteúdo da directiva deve ser escrita em sentenças completas e incluir a pontuação adequada.
  • .. warning:: Alertas são usados para documentar obstáculos em potencial, ou informação referente a segurança. O conteúdo da directiva deve ser escrito em sentenças completas e incluir a pontuação adequada.
  • .. versionadded:: X.Y.Z Admoestações de versão são usados como notas de recursos adicionados em uma versão específica, X.Y.Z sendo a versão na qual o dito recurso foi adicionado.
  • .. deprecated:: X.Y.Z O oposto das admoestações de versão, admoestações de obsolescência são usados para notificar sobre um recurso obsoleto, are used to notify of a deprecated feature, X.Y.Z sendo a versão na qual o dito recurso foi abandonado.

Todas as admoestações são feitas da mesma forma:

.. note::

    Recuadas e precedido e seguido por uma linha em branco. Assim como um
    parágrafo.

Esse texto não é parte da nota.

Exemplos

Dica

Essa é uma dica que você não sabia.

Nota

Você deve prestar atenção aqui.

Aviso

Pode ser perigoso.

Novo na versão 2.6.3: Esse recurso incrível foi adicionado na versão 2.6.3

Obsoleto desde a versão 2.6.3: Esse recurso antigo foi descontinuado na versão 2.6.3