[zh] fix sphinx warnings after cakephp#4086

en/development/rest.rst

@@ -1,28 +1,25 @@
 REST
 ####
 
-Many newer application programmers are realizing the need to open
-their core functionality to a greater audience. Providing easy,
-unfettered access to your core API can help get your platform
-accepted, and allows for mashups and easy integration with other
-systems.
-
-While other solutions exist, REST is a great way to provide easy
-access to the logic you've created in your application. It's
-simple, usually XML-based (we're talking simple XML, nothing like a
-SOAP envelope), and depends on HTTP headers for direction. Exposing
-an API via REST in CakePHP is simple.
+Many newer application programmers are realizing the need to open their core
+functionality to a greater audience. Providing easy, unfettered access to your
+core API can help get your platform accepted, and allows for mashups and easy
+integration with other systems.
+
+While other solutions exist, REST is a great way to provide easy access to the
+logic you've created in your application. It's simple, usually XML-based (we're
+talking simple XML, nothing like a SOAP envelope), and depends on HTTP headers
+for direction. Exposing an API via REST in CakePHP is simple.
 
 The Simple Setup
 ================
 
 The fastest way to get up and running with REST is to add a few lines to setup
 :ref:`resource routes <resource-routes>` in your config/routes.php file.
 
-Once the router has been set up to map REST requests to certain
-controller actions, we can move on to creating the logic in our
-controller actions. A basic controller might look something like
-this::
+Once the router has been set up to map REST requests to certain controller
+actions, we can move on to creating the logic in our controller actions. A basic
+controller might look something like this::
 
     // src/Controller/RecipesController.php
     class RecipesController extends AppController

zh/development/rest.rst

@@ -3,19 +3,19 @@ REST
 许多刚入门的开发者开始意识到他们需要把他们应用的核心功能展示（遍及）给更多的人。
 通过对外提供你应用中简单，开放的核心接口，借此可以帮助你的平台（应用）为更多的人所接受，同时允许与其他系统进行混合搭配以及简单的融合。
 
-REST可以帮你有效地向他人提供在你的应用中已创建的逻辑（方法）。 
+REST可以帮你有效地向他人提供在你的应用中已创建的逻辑（方法）。
 这非常方便，通常基于XML（这里所指的是简单的XML，并不是SOAP的那种复杂格式），同时依赖HTTP头来引导。
 在Cakephp中公开你的REST接口是非常方便的一件事。
 
 简单的设置
-================
-
+===========
 
 最快捷的方法去创建并运行REST是通过在你的配置文件config/routes.php中添加少许几行代码来配置
-:ref:`资源路由(resource routes) <resource-routes>` 
+:ref:`资源路由(resource routes) <resource-routes>`.
 
 一旦用来映射REST请求到指定控制器方法的路由已经配置好后，下一步我们就可以在控制器的方法中添加业务逻辑。
-最基本的控制器类似于以下代码：
+最基本的控制器类似于以下代码：::
+
     // src/Controller/RecipesController.php
     class RecipesController extends AppController
     {
@@ -89,6 +89,7 @@ REST可以帮你有效地向他人提供在你的应用中已创建的逻辑（
             ]);
         }
     }
+
 具有REST特性的控制器通常使用一些转换过的扩展来生成基于不同请求的不同的格式（视图）。
 既然我们现在在处理REST请求，我们将会生成一个XML的格式（视图）。
 你也可以通过CakePHP的内置方法:doc:`/views/json-and-xml-views`已达到输出JSON格式（视图）的目的。
@@ -98,18 +99,18 @@ REST可以帮你有效地向他人提供在你的应用中已创建的逻辑（
 如果我们想要在数据被转换成XML之前修改它们，我们不应该（不能）定义这个``_serialize``视图变量，而是应该使用模板文件。
 我们把RecipesController的REST视图放在**src/Template/Recipes/xml**内。或者我们也可以使用:php:class:`Xml` 类来简单快速的在这些视图中输些XML。
 
-index方法的REST视图的简单的代码
+index方法的REST视图的简单的代码::
 
     // src/Template/Recipes/xml/index.ctp
     // Do some formatting and manipulation on
     // the $recipes array.
     $xml = Xml::fromArray(['response' => $recipes]);
     echo $xml->asXML();
 
-当使用:php:meth:`Cake\\Routing\\Router::extensions()`来开放一个特殊的文档格式时，CakePHP会自动寻找匹配这个文档格式的视图helper方法。
+当使用:php:meth:`Cake\\Routing\\Router::extensions()` 来开放一个特殊的文档格式时，CakePHP会自动寻找匹配这个文档格式的视图helper方法。
 由于我们的例子中使用的是XML所以没有任何内置的helper方法，但是如果你创建了自定义的helper方法，那么它会被自动加载并在那些视图中被利用。
 
-返回的XML可能最终像下面的例子这样：
+返回的XML可能最终像下面的例子这样：::
 
     <recipes>
         <recipe>
@@ -131,27 +132,25 @@ index方法的REST视图的简单的代码
 
 创建edit方法的业务逻辑会有点懵逼，不过还好。
 由于你提供的API输出的是XML，自然来说你的第一选择是接收XML格式的数据。
-不需要担心的是，由于有了:php:class:`Cake\\Controller\\Component\\RequestHandler`和
-:php:class:`Cake\\Routing\\Router`可以让事情更简单。
-如果一个POST/PUT请求发送了XML格式的数据，那么数据会经过CakePHP的:php:class:`Xml`类的处理，所有数据都会合并到``$this->request->data``中
+不需要担心的是，由于有了:php:class:`Cake\\Controller\\Component\\RequestHandler` 和
+:php:class:`Cake\\Routing\\Router` 可以让事情更简单。
+如果一个POST/PUT请求发送了XML格式的数据，那么数据会经过CakePHP的:php:class:`Xml` 类的处理，所有数据都会合并到``$this->request->data`` 中
 因为这些特性，处理和发送XML数据是毫无阻碍的，你完全不必去修改控制器或者模型的任何代码。
-所有你需要的都会合并到``$this->request->data``中。
-
+所有你需要的都会合并到``$this->request->data`` 中。
 
 接收其他格式的数据
-================================
-典型的REST应用不仅可以输出不同格式的数据，同时也可以接收不同格式的数据
-在CakePHP中:php:class:`RequestHandlerComponent`帮助我们实现了这个目标。
-一般来说，它会解码通过POST/PUT请求所接收到的JSON/XML的任何数据并且在``$this->request->data``中告诉你数据的格式。
-当然如果你需要的话，你也可以自定义其他的反序列化方法以此丰富你的数据接收/发送格式（通过:php:meth:`RequestHandler::addInputType()`来添加）。
+==================
 
+典型的REST应用不仅可以输出不同格式的数据，同时也可以接收不同格式的数据
+在CakePHP中:php:class:`RequestHandlerComponent` 帮助我们实现了这个目标。
+一般来说，它会解码通过POST/PUT请求所接收到的JSON/XML的任何数据并且在``$this->request->data`` 中告诉你数据的格式。
+当然如果你需要的话，你也可以自定义其他的反序列化方法以此丰富你的数据接收/发送格式（通过:php:meth:`RequestHandler::addInputType()` 来添加）。
 
 具有REST特性的路由
-===============
+===================
 
 CakePHP的路由使得实现REST变得简单。
-查阅资源路由（resource-routes）:ref:`resource-routes`以获取更多信息
-
+查阅资源路由（resource-routes）:ref:`resource-routes` 以获取更多信息
 
 .. meta::
     :title lang=zh: REST

zh/development/routing.rst

@@ -16,6 +16,11 @@ Routing
     You can referer to the english version in the select top menu to have
     information about this page's topic.
 
+.. _resource-routes:
+
+Creating RESTful Routes
+=======================
+
 .. toctree::
     :glob:
     :maxdepth: 1