fix dead links and refine tutorials/index

2b4ddb38 · Luo Tao · f0449b8b · 2b4ddb38 · 2b4ddb38 · 2b4ddb38
15 changed file
--- a/doc/api/data_provider/dataprovider_cn.rst
+++ b/doc/api/data_provider/dataprovider_cn.rst
 DataProvider的介绍
 ==================

-DataProvider是PaddlePaddle负责提供数据的模块。其作用是将数据传入内存或显存，让神经网络可以进行训练或预测。用户可以通过简单使用Python接口 `PyDataProvider2 <pydataprovider2.html>`_ ，来自定义传数据的过程。如果有更复杂的使用，或者需要更高的效率，用户也可以在C++端自定义一个 ``DataProvider`` 。
+DataProvider是PaddlePaddle负责提供数据的模块。其作用是将数据传入内存或显存，让神经网络可以进行训练或预测。用户可以通过简单使用Python接口 :ref:`api_pydataprovider2` ，来自定义传数据的过程。如果有更复杂的使用，或者需要更高的效率，用户也可以在C++端自定义一个 ``DataProvider`` 。

 PaddlePaddle需要用户在网络配置（trainer_config.py）中定义使用哪种DataProvider，并且在DataProvider中实现如何访问训练文件列表（train.list）或测试文件列表（test.list）。


--- a/doc/api/data_provider/pydataprovider2_cn.rst
+++ b/doc/api/data_provider/pydataprovider2_cn.rst
+..  _api_pydataprovider2:
+
 PyDataProvider2的使用
 =====================


--- a/doc/api/trainer_config_helpers/evaluators.rst
+++ b/doc/api/trainer_config_helpers/evaluators.rst
+..  _api_trainer_config_helpers_evaluators:
+
 ==========
 Evaluators
 ==========

--- a/doc/api/trainer_config_helpers/layers.rst
+++ b/doc/api/trainer_config_helpers/layers.rst
@@ -187,6 +187,8 @@ get_output_layer
 Mixed Layer
 ===========

+..  _api_trainer_config_helpers_layers_mixed_layer:
+
 mixed_layer
 -----------
 ..  automodule:: paddle.trainer_config_helpers.layers
@@ -255,12 +257,16 @@ pooling_layer
    :members: pooling_layer
    :noindex:

+..  _api_trainer_config_helpers_layers_last_seq:
+
 last_seq
 --------
 ..  automodule:: paddle.trainer_config_helpers.layers
    :members: last_seq
    :noindex:

+..  _api_trainer_config_helpers_layers_first_seq:
+
 first_seq
 ---------
 ..  automodule:: paddle.trainer_config_helpers.layers
@@ -282,6 +288,8 @@ block_expand_layer
    :members: block_expand_layer
    :noindex:

+..  _api_trainer_config_helpers_layers_expand_layer:
+
 expand_layer
 ------------
 ..  automodule:: paddle.trainer_config_helpers.layers
@@ -374,6 +382,8 @@ sampling_id_layer
    :members: sampling_id_layer
    :noindex:

+..  _api_trainer_config_helpers_layers_cost_layers:
+
 Cost Layers
 ===========


--- a/doc/api/trainer_config_helpers/networks.rst
+++ b/doc/api/trainer_config_helpers/networks.rst
@@ -36,6 +36,8 @@ img_conv_group
    :members: img_conv_group
    :noindex:

+..  _api_trainer_config_helpers_network_simple_img_conv_pool:
+
 simple_img_conv_pool
 --------------------
 ..  automodule:: paddle.trainer_config_helpers.networks

--- a/doc/api/trainer_config_helpers/optimizers.rst
+++ b/doc/api/trainer_config_helpers/optimizers.rst
+..  _api_trainer_config_helpers_optimizers:
+
 ==========
 Optimizers
 ==========
@@ -50,6 +52,8 @@ RMSPropOptimizer
    :members: RMSPropOptimizer
    :noindex:

+..  _api_trainer_config_helpers_optimizers_settings:
+
 settings
 ========
 ..  automodule:: paddle.trainer_config_helpers.optimizers

--- a/doc/faq/index_cn.rst
+++ b/doc/faq/index_cn.rst
@@ -35,7 +35,7 @@ PyDataProvider使用的是异步加载，同时在内存里直接随即选取数

 ..  literalinclude:: src/reduce_min_pool_size.py

-这样做可以极大的减少内存占用，并且可能会加速训练过程，详细文档参考 `这里 <../ui/data_provider/pydataprovider2.html#provider>`_ 。
+这样做可以极大的减少内存占用，并且可能会加速训练过程，详细文档参考 :ref:`api_pydataprovider2` 。

 神经元激活内存
 ++++++++++++++
@@ -95,7 +95,6 @@ PaddlePaddle支持Sparse的训练，sparse训练需要训练特征是 :code:`spa

 ..  literalinclude:: src/word2vec_config.py

-更多关于sparse训练的内容请参考 `sparse训练的文档 <TBD>`_

 利用更多的计算资源
 ++++++++++++++++++
@@ -103,14 +102,15 @@ PaddlePaddle支持Sparse的训练，sparse训练需要训练特征是 :code:`spa
 利用更多的计算资源可以分为一下几个方式来进行\:

 * 单机CPU训练
+
  * 使用多线程训练。设置命令行参数 :code:`trainer_count`。

 * 单机GPU训练
+
  * 使用显卡训练。设置命令行参数 :code:`use_gpu`。
  * 使用多块显卡训练。设置命令行参数 :code:`use_gpu` 和 :code:`trainer_count` 。

-* 多机训练
-  * 具体的多机训练方法参考  `多机训练文档 <../ui/data_provider/pydataprovider2.html#provider>`_ 。
+* 多机训练（文档待补充）


 3. 遇到“非法指令”或者是“illegal instruction”
@@ -302,4 +302,4 @@ PaddlePaddle的参数使用名字 :code:`name` 作为参数的ID，相同名字
    git submodule init
    git submodule update

-来获得所有第三方模块。
\ No newline at end of file
+来获得所有第三方模块。
--- a/doc/howto/deep_model/rnn/hierarchical_layer_cn.rst
+++ b/doc/howto/deep_model/rnn/hierarchical_layer_cn.rst
@@ -22,7 +22,7 @@
 pooling_layer
 ==============

-pooling_layer 的使用示例如下，详细见 `pooling_layer`_ 配置API。
+pooling_layer 的使用示例如下，详细见 :ref:`api_trainer_config_helpers_layers_pooling_layer` 配置API。

 ..	code-block:: bash

@@ -47,7 +47,7 @@ pooling_layer 的使用示例如下，详细见 `pooling_layer`_ 配置API。
 last_seq 和 first_seq
 =====================

-last_seq 的使用示例如下（ `first_seq`_ 类似），详细见 `last_seq`_ 配置API。
+last_seq 的使用示例如下（ :ref:`api_trainer_config_helpers_layers_first_seq` 类似），详细见 :ref:`api_trainer_config_helpers_layers_last_seq` 配置API。

 ..	code-block:: bash

@@ -68,7 +68,7 @@ last_seq 的使用示例如下（ `first_seq`_ 类似），详细见 `last_seq`_
 expand_layer
 ============

-expand_layer 的使用示例如下，详细见 `expand_layer`_ 配置API。
+expand_layer 的使用示例如下，详细见 :ref:`api_trainer_config_helpers_layers_expand_layer` 配置API。

 ..	code-block:: bash

@@ -87,9 +87,3 @@ expand_layer 的使用示例如下，详细见 `expand_layer`_ 配置API。
  - 作用：一个单层序列经过运算扩展成一个双层序列
  - 输入：layer1必须是一个单层序列，是待扩展的数据；layer2 必须是一个双层序列，提供扩展的长度信息
  - 输出：一个双层序列，序列中含有元素的数目同 layer2 一致。要求单层序列含有元素的数目（0层序列）和双层序列含有subseq 的数目一致。单层序列第i个元素（0层序列），被扩展为一个单层序列，构成了输出双层序列的第i个 subseq 。
-
-
-.. _pooling_layer: ../../../doc/ui/api/trainer_config_helpers/layers.html#pooling-layer
-.. _last_seq: ../../../doc/ui/api/trainer_config_helpers/layers.html#last-seq
-.. _first_seq: ../../../doc/ui/api/trainer_config_helpers/layers.html#first-seq
-.. _expand_layer: ../../../doc/ui/api/trainer_config_helpers/layers.html#expand-layer
--- a/doc/howto/deep_model/rnn/recurrent_group_cn.md
+++ b/doc/howto/deep_model/rnn/recurrent_group_cn.md
@@ -12,7 +12,7 @@

 更进一步，`recurrent_group`同样可以扩展到双层序列的处理上。通过两个嵌套的`recurrent_group`分别定义子句级别和词语级别上需要完成的运算，最终实现一个层次化的复杂RNN。

-目前，在PaddlePaddle中，能够对双向序列进行处理的有`recurrent_group`和部分Layer，具体可参考文档：<a href = "hierarchical-layer.html">支持双层序列作为输入的Layer</a>。
+目前，在PaddlePaddle中，能够对双向序列进行处理的有`recurrent_group`和部分Layer，具体可参考文档：<a href = "hierarchical_layer_cn.html">支持双层序列作为输入的Layer</a>。
 
 ## 相关概念


--- a/doc/howto/usage/cluster/k8s/k8s_distributed_cn.md
+++ b/doc/howto/usage/cluster/k8s/k8s_distributed_cn.md
@@ -82,7 +82,7 @@ COPY start_paddle.py /root/
 CMD ["bash"," -c","/root/start.sh"]
 ```

-[`start.sh`](start.sh)文件拷贝训练文件到容器内，然后执行[`start_paddle.py`](start_paddle.py)脚本启动训练，前文提到的获取其他节点IP地址，分配`trainer_id`等都在`start_paddle.py`脚本中完成。
+[start.sh](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/howto/usage/cluster/k8s/start.sh)文件拷贝训练文件到容器内，然后执行[start_paddle.py](https://github.com/PaddlePaddle/Paddle/blob/develop/doc/howto/usage/cluster/k8s/start_paddle.py)脚本启动训练，前文提到的获取其他节点IP地址，分配`trainer_id`等都在`start_paddle.py`脚本中完成。

 `start_paddle.py`脚本开始时，会先进行参数的初始化与解析。


--- a/doc/howto/usage/concepts/use_concepts_cn.rst
+++ b/doc/howto/usage/concepts/use_concepts_cn.rst
@@ -37,7 +37,7 @@ PaddlePaddle是一个深度学习框架，支持单机模式和多机模式。

 DataProvider是PaddlePaddle系统的数据提供器，将用户的原始数据转换成系统可以识别的数据类型。每当系统需要新的数据训练时, trainer进程会调用DataProvider函数返回数据。当所有数据读取完一轮后，DataProvider返回空数据，通知系统一轮数据读取结束，并且系统每一轮训练开始时会重置DataProvider。需要注意的是，DataProvider是被系统调用，而不是新数据驱动系统，一些随机化噪声添加都应该在DataProvider中完成。

-在不同的应用里，训练数据的格式往往各不相同。因此，为了用户能够灵活的处理数据，我们提供了Python处理数据的接口，称为 `PyDataProvider`_ 。在 ``PyDataProvider`` 中，系统C++模块接管了shuffle、处理batch、GPU和CPU通信、双缓冲、异步读取等问题，一些情况下(如：``min_pool_size=0``)需要Python接口里处理shuffle，可以参考 `PyDataProvider`_ 的相关文档继续深入了解。
+在不同的应用里，训练数据的格式往往各不相同。因此，为了用户能够灵活的处理数据，我们提供了Python处理数据的接口，称为 ``PyDataProvider`` 。在 ``PyDataProvider`` 中，系统C++模块接管了shuffle、处理batch、GPU和CPU通信、双缓冲、异步读取等问题，一些情况下(如：``min_pool_size=0``)需要Python接口里处理shuffle，可以参考 :ref:`api_pydataprovider2` 继续深入了解。


 训练配置文件
@@ -50,21 +50,21 @@ DataProvider是PaddlePaddle系统的数据提供器，将用户的原始数据
 ..  literalinclude:: src/trainer_config.py
    :linenos:

-文件开头 ``from paddle.trainer_config_helpers import *`` ，是因为PaddlePaddle配置文件与C++模块通信的最基础协议是protobuf，为了避免用户直接写复杂的protobuf string，我们为用户定以Python接口来配置网络，该Python代码可以生成protobuf包，这就是`trainer_config_helpers`_的作用。因此，在文件的开始，需要import这些函数。 这个包里面包含了模型配置需要的各个模块。
+文件开头 ``from paddle.trainer_config_helpers import *`` ，是因为PaddlePaddle配置文件与C++模块通信的最基础协议是protobuf，为了避免用户直接写复杂的protobuf string，我们为用户定以Python接口来配置网络，该Python代码可以生成protobuf包，这就是 :ref:`api_trainer_config` 的作用。因此，在文件的开始，需要import这些函数。 这个包里面包含了模型配置需要的各个模块。

 下面分别介绍数据源配置、优化算法配置、网络结构配置这三部分该概念。

 数据源配置
 ----------

-使用 `PyDataProvider`_ 的函数 ``define_py_data_sources2`` 配置数据源。``define_py_data_sources2`` 里通过train_list和test_list指定是训练文件列表和测试文件列表。 如果传入字符串的话，是指一个数据列表文件。这个数据列表文件中包含的是每一个训练或者测试文件的路径。如果传入一个list的话，则会默认生成一个list文件，再传入给train.list或者test.list。
+使用 ``PyDataProvider2`` 的函数 ``define_py_data_sources2`` 配置数据源。``define_py_data_sources2`` 里通过train_list和test_list指定是训练文件列表和测试文件列表。 如果传入字符串的话，是指一个数据列表文件。这个数据列表文件中包含的是每一个训练或者测试文件的路径。如果传入一个list的话，则会默认生成一个list文件，再传入给train.list或者test.list。

-``module`` 和 ``obj`` 指定了DataProvider的文件名和返回数据的函数名。更详细的使用，请参考 `PyDataProvider`_ 。
+``module`` 和 ``obj`` 指定了DataProvider的文件名和返回数据的函数名。更详细的使用，请参考 :ref:`api_pydataprovider2` 。

 优化算法配置
 ------------

-通过 `settings`_ 接口设置神经网络所使用的训练参数和 `优化算法`_ ，包括学习率、batch_size、优化算法、正则方法等，具体的使用方法请参考 `settings`_ 文档。
+通过 :ref:`api_trainer_config_helpers_optimizers_settings` 接口设置神经网络所使用的训练参数和 :ref:`api_trainer_config_helpers_optimizers` ，包括学习率、batch_size、优化算法、正则方法等，具体的使用方法请参考 :ref:`api_trainer_config_helpers_optimizers_settings` 文档。

 网络结构配置
 ------------
@@ -82,14 +82,13 @@ DataProvider是PaddlePaddle系统的数据提供器，将用户的原始数据
 
  这个配置文件网络由 ``data_layer`` 、 ``simple_img_conv_pool`` 、 ``fc_layer`` 组成。

-  - `data_layer`_  ： 通常每个配置文件都会包括 ``data_layer`` ，定义输入数据大小。
-  - `simple_img_conv_pool`_ ：是一个组合层，包括了图像的卷积 (convolution)和池化(pooling)。
-  - `fc_layer`_ ：全连接层，激活函数为Softmax，这里也可叫分类层。
+  - :ref:`api_trainer_config_helpers_layers_data_layer`  ： 通常每个配置文件都会包括 ``data_layer`` ，定义输入数据大小。
+  - :ref:`api_trainer_config_helpers_network_simple_img_conv_pool` ：是一个组合层，包括了图像的卷积 (convolution)和池化(pooling)。
+  - :ref:`api_trainer_config_helpers_layers_fc_layer` ：全连接层，激活函数为Softmax，这里也可叫分类层。

-  
 - 损失函数和评估器：损失函数即为网络的优化目标，评估器可以评价模型结果。

-  PaddlePaddle包括很多损失函数和评估起，详细可以参考 `损失函数层`_ 和 `评估器`_ 。这里 ``classification_cost`` 默认使用多类交叉熵损失函数和分类错误率统计评估器。
+  PaddlePaddle包括很多损失函数和评估起，详细可以参考 :ref:`api_trainer_config_helpers_layers_cost_layers` 和 :ref:`api_trainer_config_helpers_evaluators` 。这里 ``classification_cost`` 默认使用多类交叉熵损失函数和分类错误率统计评估器。
  
 - ``outputs``: 标记网络输出的函数为 ``outputs`` 。

@@ -106,7 +105,7 @@ DataProvider是PaddlePaddle系统的数据提供器，将用户的原始数据
       with mixed_layer(size=200) as out:
           out += full_matrix_projection(input=data)

-PaddlePaddle 可以使用 ``mixed layer`` 配置出非常复杂的网络，甚至可以直接配置一个完整的LSTM。用户可以参考 `mixed_layer`_ 的相关文档进行配置。
+PaddlePaddle 可以使用 ``mixed layer`` 配置出非常复杂的网络，甚至可以直接配置一个完整的LSTM。用户可以参考 :ref:`api_trainer_config_helpers_layers_mixed_layer` 的相关文档进行配置。


 分布式训练
@@ -138,18 +137,3 @@ PaddlePaddle多机采用经典的 Parameter Server 架构对多个节点的 trai
 * --ports_num_for_sparse\: 一个pserver进程共绑定多少端口用来做稀疏更新，默认是0。

 使用手工指定端口数量，是因为Paddle的网络通信中，使用了 int32 作为消息长度，比较容易在大模型下溢出。所以，在 pserver 进程中可以启动多个子线程去接受 trainer 的数据，这样单个子线程的长度就不会溢出了。但是这个值不可以调的过大，因为增加这个值，对性能尤其是内存占用有一定的开销，另外稀疏更新的端口如果太大的话，很容易导致某一个参数服务器没有分配到任何参数。
-
-详细的说明可以参考，使用 `集群训练Paddle`_ 。
-
-
-..  _PyDataProvider: ../ui/data_provider/pydataprovider2.html
-.. _settings: ../../doc/ui/api/trainer_config_helpers/optimizers.html#settings
-.. _优化算法: ../../doc/ui/api/trainer_config_helpers/optimizers.html#optimizers
-.. _trainer_config_helper: ../../doc/ui/api/trainer_config_helpers/index.html
-.. _data_layer: ../../doc/ui/api/trainer_config_helpers/layers.html#data-layer
-.. _simple_img_conv_pool: ../../doc/ui/api/trainer_config_helpers/networks.html#simple-img-conv-pool
-.. _fc_layer: ../../doc/ui/api/trainer_config_helpers/layers.html#fc-layer
-.. _损失函数层: ../../doc/ui/api/trainer_config_helpers/layers.html#cost-layers
-.. _评估器: ../../doc/ui/api/trainer_config_helpers/evaluators.html
-.. _mixed_layer: ../../doc/ui/api/trainer_config_helpers/layers.html#mixed-layer
-..  _集群训练Paddle: ../cluster/index.html
--- a/doc/tutorials/index_cn.md
+++ b/doc/tutorials/index_cn.md
 # 完整教程

-## 快速入门
-
-使用商品评论分类任务，系统性的介绍如何一步步改进，最终得到产品级的深度模型。
-
-* [阅读教程](quick_start/index_cn.rst)
-
-## 图像
-
-* TBD
-
-## 自然语言处理
-
-* [情感分类](sentiment_analysis/index_cn.md)
+* [快速入门](quick_start/index_cn.rst)
+* [个性化推荐](rec/ml_regression_cn.rst)
+* [情感分析](sentiment_analysis/index_cn.md)
 * [语义角色标注](semantic_role_labeling/index_cn.md)
-
-## 个性化推荐
-
-* TBD
+* [机器翻译](text_generation/index_cn.md)

 ## 常用模型

-* TBD
+* [ResNet模型](imagenet_model/resnet_model_cn.md)
--- a/doc/tutorials/index_en.md
+++ b/doc/tutorials/index_en.md
 # TUTORIALS
 There are several examples and demos here.

-## Quick Start
-
 * [Quick Start](quick_start/index_en.md)
-
-## Image
-
+* [MovieLens Regression](rec/ml_regression_en.rst)
 * [Image Classification](image_classification/index_en.md)
-
-## NLP
-
 * [Sentiment Analysis](sentiment_analysis/index_en.md)
-* [Text Generation](text_generation/index_en.md)
 * [Semantic Role Labeling](semantic_role_labeling/index_en.md)
-
-## Recommendation
-
-* [MovieLens Regression](rec/ml_regression_en.rst)
+* [Text Generation](text_generation/index_en.md)

 ## Model Zoo
 * [ImageNet: ResNet](imagenet_model/resnet_model_en.md)

--- a/doc/tutorials/quick_start/index_en.md
+++ b/doc/tutorials/quick_start/index_en.md
@@ -391,7 +391,7 @@ paddle train \
 --use_gpu=false
 ```

-We do not provide examples on how to train on clusters here. If you want to train on clusters, please follow the <a href = "../../howto/cluster/cluster_train_en.html">distributed training</a> documentation or other demos for more details.
+We do not provide examples on how to train on clusters here. If you want to train on clusters, please follow the <a href = "../../howto/usage/cluster/cluster_train_en.html">distributed training</a> documentation or other demos for more details.

 ## Inference
 You can use the trained model to perform prediction on the dataset with no labels. You can also evaluate the model on dataset with labels to obtain its test accuracy.
@@ -509,7 +509,7 @@ The scripts of data downloading, network configurations, and training scrips are
 * \--config_args：Other configuration arguments.
 * \--init_model_path：The path of the initial model parameter.

-By default, the trainer will save model every pass. You can also specify `saving_period_by_batches` to set the frequency of batch saving. You can use `show_parameter_stats_period` to print the statistics of the parameters, which are very useful for tuning parameters. Other command line arguments can be found in <a href = "../../howto/cmd_parameter/index_en.html">command line argument documentation</a>。
+By default, the trainer will save model every pass. You can also specify `saving_period_by_batches` to set the frequency of batch saving. You can use `show_parameter_stats_period` to print the statistics of the parameters, which are very useful for tuning parameters. Other command line arguments can be found in <a href = "../../howto/usage/cmd_parameter/index_en.html">command line argument documentation</a>。

 ### Log


--- a/python/paddle/trainer_config_helpers/layers.py
+++ b/python/paddle/trainer_config_helpers/layers.py
@@ -1776,15 +1776,15 @@ def img_conv_layer(input,
                   trans=False,
                   layer_type=None):
    """
-    Convolution layer for image. Paddle only support square input currently and
-    thus input image's width equals height.
+    Convolution layer for image. Paddle can support both square and non-square 
+    input currently.

    The details of convolution layer, please refer UFLDL's `convolution
    <http://ufldl.stanford.edu/tutorial/supervised/
    FeatureExtractionUsingConvolution/>`_ .

-    Convolution Transpose (deconv) layer for image. Paddle only support square
-    input currently and thus input image's width equals height.
+    Convolution Transpose (deconv) layer for image. Paddle can support both square 
+    and non-square input currently.

    The details of convolution transpose layer,
    please refer to the following explanation and references therein