Documentação¶

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.

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.

Links¶

Existem diveros tipos de links, cada um com usos particulares.

`Link externo para php.net <https://php.net>`_

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

Veja 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.

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

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.