upgrade guide added (#2650)

* upgrade guide added

* update migration tool page

* minor change

* minor change

* update codes and format

* no ci for upgrade_guide

* minor

* minor

ci_scripts/api_white_list.txt

@@ -8,3 +8,4 @@ paddle/reader/ComposeNotAligned_cn.rst
 paddle/fluid/layers/scatter_cn.rst
 paddle/tensor/manipulation/scatter_cn.rst
 paddle/distributed/fleet/Fleet_cn.rst
+upgrade_guide_cn.md

doc/paddle/guides/index_cn.rst

@@ -2,23 +2,24 @@
 使用教程
 ########
 
-PaddlePaddle (PArallel Distributed Deep LEarning)是一个易用、高效、灵活、可扩展的深度学习框架。
+飞桨开源框架(PaddlePaddle)是一个易用、高效、灵活、可扩展的深度学习框架。
 
-您可参考PaddlePaddle的 `Github <https://github.com/PaddlePaddle/Paddle>`_ 了解详情，也可阅读 `版本说明 <../release_note_cn.html>`_ 了解新版本的特性。
-
-让我们从学习PaddlePaddle基本概念这里开始：
+您可参考飞桨框架的 `Github <https://github.com/PaddlePaddle/Paddle>`_ 了解详情，也可阅读 `版本说明 <../release_note_cn.html>`_ 了解2.0beta版本的特性。
 
+让我们从学习飞桨的基本概念这里开始：
 
 - `Tensor概念介绍 <tensor_introduction.html>`_ : 飞桨中数据的表示方式，Tensor概念介绍，
-- `版本迁移 <./migration_cn.html>`_：介绍 Paddle 1 到Paddle 2的变化与Paddle1to2转换工具的使用。
-- `动态图转静态图 <./dygraph_to_static/index_cn.html>`_：介绍 Paddle 动态图转静态图的方法 
-- `模型存储与载入 <./model_save_load_cn.html>`_：介绍 Paddle 模型与参数存储载入的方法
+- `飞桨框架2.0beta升级指南 <./upgrade_guide_cn.html>`_: 介绍飞桨开源框架2.0beta的主要变化和如何升级。
+- `版本迁移工具 <./migration_cn.html>`_: 介绍paddle1to2转换工具的使用。
+- `动态图转静态图 <./dygraph_to_static/index_cn.html>`_: 介绍飞桨动态图转静态图的方法 
+- `模型存储与载入 <./model_save_load_cn.html>`_: 介绍飞桨模型与参数存储载入的方法
 
 
 ..  toctree::
     :hidden:
 
     tensor_introduction.md
+    upgrade_guide_cn.md
     migration_cn.rst
     dygraph_to_static/index_cn.rst
     model_save_load_cn.rst

doc/paddle/guides/migration_cn.rst

-版本迁移
+版本迁移工具
 ====================
 
-飞桨框架v2.0-beta，最重要的变化为API体系的全面升级以及动态图能力的全面完善。下文将简要介绍Paddle
-2的变化。
+在飞桨框架2.0beta中，我们API的位置、命名、参数、行为，进行了系统性的调整和规范, 将API体系从1.X版本的 ``paddle.fluid.*`` 迁移到了 ``paddle.*`` 下。paddle.fluid目录下暂时保留了1.8版本API，主要是兼容性考虑，未来会被删除。
 
-主要变化
---------
-
-在飞桨框架v2.0中，我们做了许多的升级。首先，全面完善了动态图模式，相较于静态图而言，动态图每次执行一个运算，可以立即得到结果，能够使算法的开发变得更加高效。此外，本版本对API目录，进行了较大的调整。将API体系从1.X版本的
-``paddle.fluid.*`` 迁移到了 ``paddle.*`` 下。原则上，Paddle
-2仍支持Paddle 1下的所有语法。但是，我们会逐步废弃掉 ``paddle.fluid``
-下的API，强烈建议您将Paddle 1的代码迁移到Paddle
-2下，以避免后续带来不必要的麻烦。下文将介绍手动与自动两种方式，来完成Paddle
-1到Paddle 2的迁移。
-
-手动将Paddle 1 的代码迁移到 Paddle 2
-------------------------------------
-
-本节将介绍如何将您的代码手动的从Paddle 1迁移到Paddle 2。
-
-1、API的变化
-~~~~~~~~~~~~
-
-对于Paddle
-1下的API，您可以通过我们提供的API升级表（TODO），查看每个API的升级关系，从而手动完成修改。
-### 2、句法的变化 在Paddle 1中，通过 ``with fluid.dygraph.guard():``
-开启动态图模式，在Paddle 2.0-beta中，可以直接通过
-``paddle.disable_static()``\ 开启动态图。
-
-Paddle1to2 自动迁移您的代码到Paddle2
+使用版本迁移工具自动迁移您的paddle1.x的代码到Paddle2.0beta的代码
 ------------------------------------
 
-Paddle 2 包含了许多API的变化，为了节约您将代码从Paddle 1迁移到Paddle
-2的时间，我们提供了自动迁移工具–Paddle1to2，能够帮助您快速完成代码迁移。
+WARNING: 版本自动迁移工具并不能处理所有的情况，在使用本工具后，您仍然需要手工来进行检查并做相应的调整。
 
 安装
 ~~~~
 
-Paddle1to2可以通过pip的方式安装，方式如下:
+paddle1to2工具可以通过pip的方式安装，方式如下:
 
 .. code:: ipython3
 
@@ -52,8 +26,7 @@ Paddle1to2 可以使用下面的方式，快速使用:
 
     ! paddle1to2 --inpath /path/to/model.py
 
-这将在命令行中，以\ ``diff``\ 的形式，展示model.py从Paddle 1转换为Paddle
-2的变化。如果您确认上述变化没有问题，只需要再执行：
+这将在命令行中，以\ ``diff``\ 的形式，展示model.py从Paddle1.x转换为Paddle2.0beta的变化。如果您确认上述变化没有问题，只需要再执行：
 
 .. code:: ipython3
 
@@ -86,27 +59,24 @@ Paddle1to2 可以使用下面的方式，快速使用:
 开始
 ^^^^
 
-在使用Paddle 1to2前，需要确保您已经安装了Paddle 2.0-beta版本。
+在使用paddle1to2前，需要确保您已经安装了Paddle2.0beta版本。
 
 .. code:: ipython3
 
     import paddle
     print (paddle.__version__)
-    # TODO change to paddle 2.0-beta
-
 
 .. parsed-literal::
 
-    0.0.0
+    2.0.0-beta0
 
 
-克隆\ `PaddlePaddle/models <https://github.com/PaddlePaddle/models>`__\ 来作为工具的测试。
+克隆\ `paddlePaddle/models <https://github.com/PaddlePaddle/models>`__\ 来作为工具的测试。
 
 .. code:: ipython3
 
     ! git clone https://github.com/PaddlePaddle/models
 
-
 .. parsed-literal::
 
     Cloning into 'models'...
@@ -121,8 +91,7 @@ Paddle1to2 可以使用下面的方式，快速使用:
 查看帮助文档
 ^^^^^^^^^^^^
 
-paddle1to2 会随着 paddle
-2.0-beta安装。所以您可以直接通过下面的方式，查看帮助文档。
+您可以直接通过下面的方式，查看帮助文档。
 
 .. code:: ipython3
 
@@ -131,66 +100,66 @@ paddle1to2 会随着 paddle
 
 .. parsed-literal::
 
-    usage: paddle1to2 [-h] [--log-level {DEBUG,INFO,WARNING,ERROR}]
-                      [--no-log-file] [--log-filepath LOG_FILEPATH] --inpath
-                      INPATH [--backup [BACKUP]] [--write] [--no-confirm]
-                      [--refactor {refactor_import,norm_api_alias,args_to_kwargs,refactor_kwargs,api_rename,refactor_with,post_refactor}]
-                      [--print-match]
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --log-level {DEBUG,INFO,WARNING,ERROR}
-                            set log level, default is INFO
-      --no-log-file         don't log to file
-      --log-filepath LOG_FILEPATH
-                            set log file path, default is "report.log"
-      --inpath INPATH       the file or directory path you want to upgrade.
-      --backup [BACKUP]     backup directory, default is the "~/.paddle1to2/".
-      --write               modify files in-place.
-      --no-confirm          write files in-place without confirm, ignored without
-                            --write.
-      --refactor {refactor_import,norm_api_alias,args_to_kwargs,refactor_kwargs,api_rename,refactor_with,post_refactor}
-                            this is a debug option. Specify refactor you want to
-                            run. If none, all refactors will be run.
-      --print-match         this is a debug option. Print matched code and node
-                            for each file.
-
-
-Paddle 1的例子
+    usage: paddle1to2 [-h] [--log-level {DEBUG,INFO,WARNING,ERROR}]
+                      [--no-log-file] [--log-filepath LOG_FILEPATH] --inpath
+                      INPATH [--backup [BACKUP]] [--write] [--no-confirm]
+                      [--refactor {refactor_import,norm_api_alias,args_to_kwargs,refactor_kwargs,api_rename,refactor_with,post_refactor}]
+                      [--print-match]
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --log-level {DEBUG,INFO,WARNING,ERROR}
+                            set log level, default is INFO
+      --no-log-file         don't log to file
+      --log-filepath LOG_FILEPATH
+                            set log file path, default is "report.log"
+      --inpath INPATH       the file or directory path you want to upgrade.
+      --backup [BACKUP]     backup directory, default is the "~/.paddle1to2/".
+      --write               modify files in-place.
+      --no-confirm          write files in-place without confirm, ignored without
+                            --write.
+      --refactor {refactor_import,norm_api_alias,args_to_kwargs,refactor_kwargs,api_rename,refactor_with,post_refactor}
+                            this is a debug option. Specify refactor you want to
+                            run. If none, all refactors will be run.
+      --print-match         this is a debug option. Print matched code and node
+                            for each file.
+
+
+paddle1.x的例子
 ^^^^^^^^^^^^^^
 
-这里是一个基于Paddle 1实现的一个mnist分类，部分内容如下：
+这里是一个基于paddle1.x实现的一个mnist分类，部分内容如下：
 
 .. code:: ipython3
 
     ! head -n 198 models/dygraph/mnist/train.py | tail -n  20
 
 
-.. parsed-literal::
+.. code:: ipython3
 
-        with fluid.dygraph.guard(place):
-            if args.ce:
-                print("ce mode")
-                seed = 33
-                np.random.seed(seed)
-                fluid.default_startup_program().random_seed = seed
-                fluid.default_main_program().random_seed = seed
-    
-            if args.use_data_parallel:
-                strategy = fluid.dygraph.parallel.prepare_context()
-            mnist = MNIST()
-            adam = AdamOptimizer(learning_rate=0.001, parameter_list=mnist.parameters())
-            if args.use_data_parallel:
-                mnist = fluid.dygraph.parallel.DataParallel(mnist, strategy)
-    
-            train_reader = paddle.batch(
-                paddle.dataset.mnist.train(), batch_size=BATCH_SIZE, drop_last=True)
-            if args.use_data_parallel:
-                train_reader = fluid.contrib.reader.distributed_batch_reader(
-                    train_reader)
-
-
-使用Paddle1to2进行转化
+        with fluid.dygraph.guard(place):
+            if args.ce:
+                print("ce mode")
+                seed = 33
+                np.random.seed(seed)
+                fluid.default_startup_program().random_seed = seed
+                fluid.default_main_program().random_seed = seed
+ 
+            if args.use_data_parallel:
+                strategy = fluid.dygraph.parallel.prepare_context()
+            mnist = MNIST()
+            adam = AdamOptimizer(learning_rate=0.001, parameter_list=mnist.parameters())
+            if args.use_data_parallel:
+                mnist = fluid.dygraph.parallel.DataParallel(mnist, strategy)
+ 
+            train_reader = paddle.batch(
+                paddle.dataset.mnist.train(), batch_size=BATCH_SIZE, drop_last=True)
+            if args.use_data_parallel:
+                train_reader = fluid.contrib.reader.distributed_batch_reader(
+                    train_reader)
+
+
+使用paddle1to2进行转化
 ^^^^^^^^^^^^^^^^^^^^^^
 
 paddle1to2支持单文件的转化，您可以通过下方的命令直接转化单独的文件。
@@ -227,8 +196,7 @@ paddle1to2支持单文件的转化，您可以通过下方的命令直接转化
 
 -  本迁移工具不能完成所有API的迁移，有少量的API需要您手动完成迁移，具体信息可见WARNING。
 
-使用Paddle 2
+使用paddle 2
 ~~~~~~~~~~~~
 
-完成迁移后，代码就从Paddle 1迁移到了Paddle 2，您就可以在Paddle
-2下进行相关的开发。
+完成迁移后，代码就从paddle1.x迁移到了paddle2.0beta，您就可以在paddle2.0beta下进行相关的开发。