[all lang] add orphan option to avoid sphinx build warning

HughbertD · Sep 12, 2015 · 6023e50 · 6023e50
1 parent 91a7014
commit 6023e50
Show file tree

Hide file tree

Showing 17 changed files with 113 additions and 42 deletions.
diff --git a/en/contributing/documentation.rst b/en/contributing/documentation.rst
@@ -262,6 +262,16 @@ Cross Referencing Links
     The link's text would be the title that the link preceded. You can also
     provide custom link text using ``:ref:`Link text <label-name>```.
 
+Prevent Sphinx to Output Warnings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx will output warnings if a file is not referenced in a toc-tree. It's
+a great way to ensure that all files have a link directed to them, but
+sometimes, you don't need to insert a link for a file, eg. for our
+`epub-contents` and `pdf-contents` files. In those cases, you can add
+``:orphan:`` at the top of the file, and the warnings will stop to alert you
+that the file is not in the toc-tree.
+
 Describing Classes and their Contents
 -------------------------------------
 

diff --git a/en/epub-contents.rst b/en/epub-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 

diff --git a/en/pdf-contents.rst b/en/pdf-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 

diff --git a/es/epub-contents.rst b/es/epub-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 
@@ -10,4 +12,3 @@ Contents
    tutorials-and-examples
 
 .. todolist::
-
diff --git a/es/pdf-contents.rst b/es/pdf-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 

diff --git a/fr/contributing/documentation.rst b/fr/contributing/documentation.rst
@@ -272,6 +272,16 @@ Les liens croisés de référencement
     lien. Vous pouvez aussi fournir un texte de lien sur mesure en utilisant
     ``:ref:`Texte de lien <nom-label>```.
 
+Prevent Sphinx to Output Warnings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx will output warnings if a file is not referenced in a toc-tree. It's
+a great way to ensure that all files have a link directed to them, but
+sometimes, you don't need to insert a link for a file, eg. for our
+`epub-contents` and `pdf-contents` files. In those cases, you can add
+``:orphan:`` at the top of the file, and the warnings will stop to alert you
+that the file is not in the toc-tree.
+
 Description des classes et de leur contenu
 ------------------------------------------
 

diff --git a/fr/epub-contents.rst b/fr/epub-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contenu
 #######
 

diff --git a/fr/pdf-contents.rst b/fr/pdf-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 

diff --git a/ja/contributing/documentation.rst b/ja/contributing/documentation.rst
@@ -251,6 +251,16 @@ ReST (Re Structured Text) は markdown や textile と同様のプレーンテ
     リンクのテキストはリンクの先にあるタイトルになります。また、
     ``:ref:`リンクテキスト <ラベル名>``` として自由にリンクのテキストを指定することができます。
 
+Prevent Sphinx to Output Warnings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx will output warnings if a file is not referenced in a toc-tree. It's
+a great way to ensure that all files have a link directed to them, but
+sometimes, you don't need to insert a link for a file, eg. for our
+`epub-contents` and `pdf-contents` files. In those cases, you can add
+``:orphan:`` at the top of the file, and the warnings will stop to alert you
+that the file is not in the toc-tree.
+
 クラスとその内容を記述する
 --------------------------
 

diff --git a/ja/epub-contents.rst b/ja/epub-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 コンテンツ
 ##########
 
@@ -20,4 +22,3 @@
    appendices
 
 .. todolist::
-
diff --git a/ja/pdf-contents.rst b/ja/pdf-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 

diff --git a/pt/contributing/documentation.rst b/pt/contributing/documentation.rst
@@ -2,17 +2,17 @@ Documentação
 ############
 
 Contribuir na documentação é simples. Os arquivos estão
-no https://github.com/cakephp/docs. Sinta-se livre para fazer 
-um fork e adicionar suas alterações/melhorias/traduções e enviar 
+no https://github.com/cakephp/docs. Sinta-se livre para fazer
+um fork e adicionar suas alterações/melhorias/traduções e enviar
 através de um pull request.
-Você também pode editar os arquivos online através do github, 
+Você também pode editar os arquivos online através do github,
 sem precisar fazer o download dos arquivos.
 
 Traduções
 =========
 
 Envie um email para o equipe da documentação (docs [at] cakephp dot org)
-ou entre no IRC(#cakephp on freenode) para discutir algum processo de 
+ou entre no IRC(#cakephp on freenode) para discutir algum processo de
 tradução que você queira participar.
 
 Algumas dicas:
@@ -23,7 +23,7 @@ Algumas dicas:
 - Utilize a
   `linguagem informal <http://pt.wikipedia.org/wiki/Linguagem_coloquial>`_.
 - Traduza o conteúdo e o título ao mesmo tempo.
-- Faça uma comparação com o Inglês antes de enviar uma correção. 
+- Faça uma comparação com o Inglês antes de enviar uma correção.
   (Se você corrigir alguma coisa, mas não sincroniza com o 'upstream' a
   alteração não será aceita.)
 - Se você precisa escrever termos em Inglês, utilize a tag ``<em>``.
@@ -81,7 +81,7 @@ Marcações
 * 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 
+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:
@@ -99,13 +99,13 @@ 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. 
+    * Essa também.
       Mas tem duas linhas
-      
-      
+
+
     1. Primeira linha
     2. Segunda linha
-    
+
     #. Númeração automatica
     #. Vai salvar seu tempo.
 
@@ -114,10 +114,10 @@ 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::
@@ -168,18 +168,28 @@ Links de referência cruzada
     melhor usar ``class-method`` como *label* do link.
 
     A forma mais comum de usar *labels* é acima de títulos. Exemplo::
-    
+
         .. _label-name:
-        
+
         Título de seção
         ---------------
-        
+
         Restante do conteúdo
-    
+
     Em qualquer lugar você pode referenciar a seção acima usando ``:ref:`label-name```.
     O texto do link será título da seção. Você também pode informar um texto personalizado
     usando ``:ref: `Link text <label-name>```.
 
+Prevent Sphinx to Output Warnings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx will output warnings if a file is not referenced in a toc-tree. It's
+a great way to ensure that all files have a link directed to them, but
+sometimes, you don't need to insert a link for a file, eg. for our
+`epub-contents` and `pdf-contents` files. In those cases, you can add
+``:orphan:`` at the top of the file, and the warnings will stop to alert you
+that the file is not in the toc-tree.
+
 Descrevendo classes e seus conteúdos
 ------------------------------------
 
@@ -206,7 +216,7 @@ Cada diretiva alimenta o índice e/ou o *namespace* do índice.
 
    Essa diretiva declara uma constante, você também pode usar
    dentro de uma classe para declarar uma constante da classe.
-   
+
 .. rst:directive:: .. php:exception:: name
 
    Essa diretiva declara um nova *Exception* no *namespace* atual.
@@ -218,38 +228,38 @@ Cada diretiva alimenta o índice e/ou o *namespace* do índice.
    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
-        
+
 
    .. seealso:: :rst:dir:`php:method`, :rst:dir:`php:attr`, :rst:dir:`php:const`
 
 .. rst:directive:: .. 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.
 
 .. rst:directive:: .. php:staticmethod:: ClassName::methodName(signature)
@@ -274,12 +284,12 @@ se alguma diretiva for encontrada:
 .. rst:role:: php:global
 
    Cria uma referência para uma variável global que comece com ``$``.
-   
+
 .. rst:role:: php:const
 
    Cria uma referência para um constante ou uma contante de uma classe. As constantes da classe
    devem ser precedidas com o nome da classe::
-   
+
         DateTime tem uma constante :php:const:`DateTime::ATOM`.
 
 .. rst:role:: php:class
@@ -291,14 +301,14 @@ se alguma diretiva for encontrada:
 .. rst:role:: php:meth
 
    Cria uma referência para um método da classe. Essa função suporta os dois métodos::
-   
+
      :php:meth:`DateTime::setDate`
      :php:meth:`Classname::staticMethod`
 
 .. rst:role:: php:attr
 
    Cria uma referência para a propriedade de um objeto::
-   
+
       :php:attr:`ClassName::$propertyName`
 
 .. rst:role:: php:exc
@@ -313,11 +323,11 @@ 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.
@@ -335,15 +345,15 @@ Existe três tipos de *admonitions*.
 * ``.. 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 
+  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.
 
 Exemplos

diff --git a/pt/epub-contents.rst b/pt/epub-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 
@@ -20,4 +22,3 @@ Contents
    appendices
 
 .. todolist::
-
diff --git a/pt/pdf-contents.rst b/pt/pdf-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Conteúdo
 ########
 

diff --git a/zh/contributing/documentation.rst b/zh/contributing/documentation.rst
@@ -3,7 +3,7 @@
 
 给文档做贡献是很简单的。这些文件都托管在 https://github.com/cakephp/docs。请自行
 复制(*fork*)代码仓库，加入你的更改/改进/翻译，然后发出拉取请求来提交你的改动。你
-甚至可以在 GitHub 上在线地编辑文档，而完全不用下载文件--在任何页面上的"Improve 
+甚至可以在 GitHub 上在线地编辑文档，而完全不用下载文件--在任何页面上的"Improve
 this Doc"按键将会引导你进入该页面的 GitHub 在线编辑器。
 
 CakePHP文档是
@@ -237,10 +237,20 @@ ReST (Re Structured Text)是与 markdown 或者 textile 类似的纯文本标记
     之后的标题。你也可以使用 ``:ref:`链接文字 <标签名称>``` 的方式来提供自定义的
     链接文字。
 
+Prevent Sphinx to Output Warnings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sphinx will output warnings if a file is not referenced in a toc-tree. It's
+a great way to ensure that all files have a link directed to them, but
+sometimes, you don't need to insert a link for a file, eg. for our
+`epub-contents` and `pdf-contents` files. In those cases, you can add
+``:orphan:`` at the top of the file, and the warnings will stop to alert you
+that the file is not in the toc-tree.
+
 描述类和它们的内容
 ------------------
 
-CakePHP 文档使用 
+CakePHP 文档使用
 `phpdomain <http://pypi.python.org/pypi/sphinxcontrib-phpdomain>`_ 提供自定义指
 令描述 PHP 对象和结构。我们必须使用这些指令和角色，才能保证正确的索引和交叉引用。
 

diff --git a/zh/epub-contents.rst b/zh/epub-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
 

diff --git a/zh/pdf-contents.rst b/zh/pdf-contents.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Contents
 ########
-Original file line number
+Diff line change
@@ -1,3 +1,5 @@
+    :orphan:
     Contenu
     #######
@@ Expand Down @@