Merge pull request #1871 from QiJune/feature/complete_howto_write_docs_cn

complete the doc that guides generating paddle docs

doc/howto/dev/write_docs_cn.rst

@@ -8,7 +8,8 @@ PaddlePaddle的文档包括英文文档 ``doc`` 和中文文档 ``doc_cn`` 两
 如何构建PaddlePaddle的文档
 ==========================
 
-PaddlePaddle的文档构建有直接构建和基于Docker构建两种方式。构建PaddlePaddle文档需要准备的环境相对较复杂，所以我们推荐使用基于Docker来构建PaddlePaddle的文档。
+PaddlePaddle的文档构建有直接构建和基于Docker构建两种方式，我们提供了一个构建脚本build_docs.sh来进行构建。
+PaddlePaddle文档需要准备的环境相对较复杂，所以我们推荐使用基于Docker来构建PaddlePaddle的文档。
 
 
 使用Docker构建PaddlePaddle的文档
@@ -16,39 +17,62 @@ PaddlePaddle的文档构建有直接构建和基于Docker构建两种方式。
 
 使用Docker构建PaddlePaddle的文档，需要在系统里先安装好Docker工具包。Docker安装请参考 `Docker的官网 <https://docs.docker.com/>`_ 。安装好Docker之后可以使用源码目录下的脚本构建文档，即
 
-..	code-block:: bash
+..  code-block:: bash
 
-	cd TO_YOUR_PADDLE_CLONE_PATH
-	cd paddle/scripts/tools/build_docs
-	bash build_docs.sh
+    cd TO_YOUR_PADDLE_CLONE_PATH
+    cd paddle/scripts/tools/build_docs
+    bash build_docs.sh with_docker
 
-编译完成后，该目录下会生成如下两个子目录\:
+编译完成后，会在当前目录生成两个子目录\:
 
 * doc 英文文档目录
 * doc_cn 中文文档目录
 
 打开浏览器访问对应目录下的index.html即可访问本地文档。
 
-..	code-block:: bash
-
-	open doc_cn/index.html
 
 
 直接构建PaddlePaddle的文档
 --------------------------
 
-TBD
+因为PaddlePaddle的v2 api文档生成过程依赖于py_paddle Python包，用户需要首先确认py_paddle包已经安装。
+
+..  code-block:: bash
+
+    python -c "import py_paddle"
+
+如果提示错误，那么用户需要在本地编译安装PaddlePaddle，请参考 `源码编译文档 <http://www.paddlepaddle.org/develop/doc/getstarted/build_and_install/build_from_source_en.html>`_ 。
+注意，用户在首次编译安装PaddlePaddle时，请将WITH_DOC选项关闭。在编译安装正确之后，请再次确认py_paddle包已经安装，即可进行下一步操作。
+
+如果提示正确，可以执行以下命令编译生成文档，即
+
+..  code-block:: bash
+
+    cd TO_YOUR_PADDLE_CLONE_PATH
+    cd paddle/scripts/tools/build_docs
+    bash build_docs.sh local
+
+编译完成之后，会在当前目录生成两个子目录\:
+
+* doc 英文文档目录
+* doc_cn 中文文档目录
+
+打开浏览器访问对应目录下的index.html即可访问本地文档。
+
 
 如何书写PaddlePaddle的文档
 ==========================
 
-TBD
+PaddlePaddle文档使用 `sphinx`_ 自动生成，用户可以参考sphinx教程进行书写。
 
 如何更新www.paddlepaddle.org文档
 ================================
 
-TBD
+开发者给PaddlePaddle代码增加的注释以PR的形式提交到github中，提交方式可参见 `贡献文档 <http://paddlepaddle.org/develop/doc_cn/howto/dev/contribute_to_paddle_cn.html>`_ 。
+目前PaddlePaddle的develop分支的文档是自动触发更新的，用户可以分别查看最新的 `中文文档 <http://www.paddlepaddle.org/develop/doc_cn/>`_ 和
+`英文文档 <http://www.paddlepaddle.org/develop/doc/>`_ 。
+
 
 
-..	_cmake: https://cmake.org/
-..	_sphinx: http://www.sphinx-doc.org/en/1.4.8/
+..  _cmake: https://cmake.org/
+..  _sphinx: http://www.sphinx-doc.org/en/1.4.8/

paddle/scripts/docker/build.sh

@@ -57,7 +57,13 @@ if [ ${WITH_DOC} == "ON" ]; then
           -DWITH_SWIG_PY=ON \
           -DWITH_STYLE_CHECK=OFF
     make paddle_docs paddle_docs_cn
+    DOC_DIR="/paddle/paddle/scripts/tools/build_docs/"
+    mkdir -p $DOC_DIR/doc
+    mkdir -p $DOC_DIR/doc_cn
+    cp -r /paddle/build_doc/doc/en/html/* $DOC_DIR/doc
+    cp -r /paddle/build_doc/doc/cn/html/* $DOC_DIR/doc_cn
     popd
+    rm -rf /paddle/build_doc
 fi
 # generate deb package for current build
 # FIXME(typhoonzero): should we remove paddle/scripts/deb ?

paddle/scripts/tools/build_docs/Dockerfile

-FROM paddledev/paddle:cpu-devel-latest
-COPY build.sh /
-RUN pip install sphinx &&\
-    pip install sphinx_rtd_theme &&\
-    apt install -y doxygen graphviz &&\
-    pip install recommonmark numpy protobuf==2.6.1
-CMD /build.sh

paddle/scripts/tools/build_docs/build.sh

-#!/bin/bash
-set -ex
-
-mkdir -p /build
-cd /build
-cmake /paddle -DWITH_DOC=ON
-make paddle_docs paddle_docs_cn -j `nproc`
-mkdir -p /output/doc
-mkdir -p /output/doc_cn
-cp -r doc/html/* /output/doc/
-cp -r doc_cn/html/* /output/doc_cn/
-cd /
-rm -rf /paddle/build

paddle/scripts/tools/build_docs/build_docs.sh

 #!/bin/bash
 set -e
-docker build . -t paddle_build_doc
-docker run --rm -v $PWD/../../../../:/paddle -v $PWD:/output paddle_build_doc
+function usage(){
+        echo "usage: build_doc [--help] [<args>]"
+        echo "This script generates doc and doc_cn in the script's directory."
+        echo "These are common commands used in various situations:"
+        echo "    with_docker       build doc and doc_cn with docker"
+        echo "    local             build doc and doc_cn locally"
+}
+
+
+case "$1" in
+    "with_docker")
+        docker run --rm -v $PWD/../../../../:/paddle \
+            -e "WITH_GPU=OFF" -e "WITH_AVX=ON" -e "WITH_DOC=ON" paddledev/paddle:dev
+        ;;
+    "local")
+        mkdir -p doc
+        mkdir -p doc_cn
+        PADDLE_SOURCE_DIR=$PWD/../../../../
+        mkdir -p $PADDLE_SOURCE_DIR/build_doc
+        pushd $PADDLE_SOURCE_DIR/build_doc
+        cmake .. -DWITH_DOC=ON
+        make paddle_docs paddle_docs_cn
+        popd
+        cp -r $PADDLE_SOURCE_DIR/build_doc/doc/en/html/* doc
+        cp -r $PADDLE_SOURCE_DIR/build_doc/doc/cn/html/* doc_cn
+        rm -rf $PADDLE_SOURCE_DIR/build_doc
+        ;;
+    "--help")
+        usage
+        ;;
+    *)
+        usage
+        ;;
+esac