From 522f9c4b4a46eb409714406739a3e5bb581810bd Mon Sep 17 00:00:00 2001 From: "Michael (XIAO Xufeng)" Date: Tue, 31 Jul 2018 12:34:10 +0800 Subject: [PATCH] docs: translate the version include script to Chinese --- docs/gen-version-specific-includes.py | 47 +++++++++++++++++++-- docs/zh_CN/Makefile | 61 +++++++++++++++------------ docs/zh_CN/get-started/index.rst | 36 ++++++---------- 3 files changed, 91 insertions(+), 53 deletions(-) diff --git a/docs/gen-version-specific-includes.py b/docs/gen-version-specific-includes.py index b4b1bb3b1..b435e0aa9 100755 --- a/docs/gen-version-specific-includes.py +++ b/docs/gen-version-specific-includes.py @@ -1,4 +1,5 @@ #!/usr/bin/env python +# -*- coding: utf-8 -*- # # Python script to generate ReSTructured Text .inc snippets # with version-based content for this IDF version @@ -28,7 +29,7 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``. %(zipfile_note)s """ ,"master" : 'This command will clone the master branch, which has the latest development ("bleeding edge") version of ESP-IDF. It is fully functional and updated on weekly basis with the most recent features and bugfixes.' - ,"branch" : 'The ``git clone`` option ``-b %s`` tells git to clone the %s in the ESP-IDF repository corresponding to this version of the documentation.' + ,"branch" : 'The ``git clone`` option ``-b %(clone_arg)s`` tells git to clone the %(ver_type)s in the ESP-IDF repository corresponding to this version of the documentation.' ,"zipfile" : { "stable" : 'As a fallback, it is also possible to download a zip file of this stable release from the `Releases page`_. Do not download the "Source code" zip file(s) generated automatically by GitHub, they do not work with ESP-IDF.' ,"unstable" : 'GitHub\'s "Download zip file" feature does not work with ESP-IDF, a ``git clone`` is required. As a fallback, `Stable version`_ can be installed without Git.' @@ -49,7 +50,47 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``. """ }, # version-note }, # en - "zh_CN" : None # TODO: translate these snippets to Chinese + "zh_CN" : { + "git-clone" : { + "template" : """ +获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库:: + + cd ~/esp + git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git + +ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。 + +.. note:: + + %(extra_note)s + +.. note:: + + %(zipfile_note)s +""" + ,"master" : '此命令将克隆 master 分支，该分支保存着 ESP-IDF 的最新版本，它功能齐全，每周都会更新一些新功能并修正一些错误。' + ,"branch" : '``git clone`` 命令的 ``-b %(clone_arg)s`` 选项告诉 git 从 ESP-IDF 仓库中克隆与此版本的文档对应的分支。' + ,"zipfile" : { + "stable" : '作为备份，还可以从 `Releases page`_ 下载此稳定版本的 zip 文件。不要下载由 GitHub 自动生成的"源代码"的 zip 文件，它们不适用于 ESP-IDF。' + ,"unstable" : 'GitHub 中"下载 zip 文档"的功能不适用于 ESP-IDF，所以需要使用 ``git clone`` 命令。作为备份，可以在没有安装 Git 的环境中下载 `Stable version`_ 的 zip 归档文件。' + }, # zipfile + }, # git-clone + "version-note" : { + "master" : """ +.. note:: + 这是ESP-IDF master 分支（最新版本）的文档，该版本在持续开发中。还有 `Stable version`_ 的文档，以及其他版本的文档 :doc:`/versions` 供参考。 + This is documentation for the master branch (latest version) of ESP-IDF. This version is under continual development. `Stable version`_ documentation is available, as well as other :doc:`/versions`. +""" + ,"stable" : """ +.. note:: + 这是ESP-IDF 稳定版本 %s 的文档，还有其他版本的文档 :doc:`/versions` 供参考。 +""" + ,"branch" : """ +.. note:: + 这是ESP-IDF %s ``%s`` 版本的文档，还有其他版本的文档 :doc:`/versions` 供参考。 +""" + }, # version-note + }# zh_CN } @@ -84,7 +125,7 @@ def write_git_clone_inc(template, out_dir, version, ver_type, is_stable): else: args = { "clone_args" : "-b %s " % version, - "extra_note" : template["branch"] % (version, ver_type), + "extra_note" : template["branch"] % {"clone_arg" : version, "ver_type" : ver_type}, "zipfile_note" : zipfile["stable"] if is_stable else zipfile["unstable"] } out_file = os.path.join(out_dir, "git-clone.inc") diff --git a/docs/zh_CN/Makefile b/docs/zh_CN/Makefile index cc32abbd5..5ce3da55f 100644 --- a/docs/zh_CN/Makefile +++ b/docs/zh_CN/Makefile @@ -9,7 +9,7 @@ BUILDDIR = _build # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/) endif # Internal variables. @@ -19,10 +19,10 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) -w # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext dependencies version-specific-includes help: - @echo "Please use \`make ' where is one of" + @echo "Please use \`make \' where is one of" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @@ -44,43 +44,46 @@ help: @echo " xml to make Docutils-native XML files" @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " doctest to run all doctests embedded in the documentation (if enabled) " clean: rm -rf $(BUILDDIR)/* -html: +# Add any dependencies for Sphinx code generation here +dependencies: version-specific-includes + +html: dependencies $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." -dirhtml: +dirhtml: dependencies $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -singlehtml: +singlehtml: dependencies $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." -pickle: +pickle: dependencies $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." -json: +json: dependencies $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." -htmlhelp: +htmlhelp: dependencies $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." -qthelp: +qthelp: dependencies $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ @@ -89,7 +92,7 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ReadtheDocsTemplate.qhc" -devhelp: +devhelp: dependencies $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @@ -98,70 +101,70 @@ devhelp: @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ReadtheDocsTemplate" @echo "# devhelp" -epub: +epub: dependencies $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." -latex: +latex: dependencies $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." -latexpdf: +latexpdf: dependencies $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." -latexpdfja: +latexpdfja: dependencies $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through platex and dvipdfmx..." $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." -text: +text: dependencies $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." -man: +man: dependencies $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." -texinfo: +texinfo: dependencies $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." -info: +info: dependencies $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." -gettext: +gettext: dependencies $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." -changes: +changes: dependencies $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." -linkcheck: +linkcheck: dependencies $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." -gh-linkcheck: +gh-linkcheck: dependencies @echo "Checking for hardcoded GitHub links" @if (find ../ -name '*.rst' | xargs grep \ 'https://github.com/espressif/esp-idf/tree\|https://github.com/espressif/esp-idf/blob\|https://github.com/espressif/esp-idf/raw'\ @@ -185,17 +188,21 @@ gh-linkcheck: fi @echo "No hardcoded links found" -doctest: +doctest: dependencies $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." -xml: +xml: dependencies $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml @echo @echo "Build finished. The XML files are in $(BUILDDIR)/xml." -pseudoxml: +pseudoxml: dependencies $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +version-specific-includes: + mkdir -p $(BUILDDIR)/inc + ../gen-version-specific-includes.py zh_CN $(BUILDDIR)/inc diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index ba7aa5a7b..6e38dbdfc 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -5,6 +5,8 @@ 本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子来说明如何使用 ESP-IDF (Espressif IoT Development Framework)，包括配置、编译、下载固件到开发板等步骤。 +.. include:: /_build/inc/version-note.inc + 概述 ====== @@ -73,7 +75,7 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了 :hidden: Windows - Linux + Linux MacOS +-------------------+-------------------+-------------------+ @@ -110,12 +112,11 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了 .. highlight:: bash -工具链（包括用于编译和构建应用程序的程序）安装完后，你还需要 ESP32 相关的 API/库。API/库在 `ESP-IDF 仓库 `_ 中。要获取这些 API/库，打开一个终端，进入某个你希望存放 ESP-IDF 的目录，然后 ``git clone`` 以下指令： :: +工具链（包括用于编译和构建应用程序的程序）安装完后，你还需要 ESP32 相关的 API/库。API/库在 `ESP-IDF 仓库 `_ 中。 - cd ~/esp - git clone --recursive https://github.com/espressif/esp-idf.git +.. include:: /_build/inc/git-clone.inc -ESP-IDF 将会被下载到 ``~/esp/esp-idf``。 +查看 :doc:/versions 以获取不同情况下选择要使用的分支的帮助。 .. note:: @@ -176,7 +177,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 :figclass: align-center 工程配置 - 主窗口 - + 在菜单中，进入 ``Serial flasher config`` > ``Default serial port`` 配置串口（工程将会加载到该串口上）。输入回车确认选择，选择 ``< Save >`` 保存配置，然后选择 ``< Exit >`` 退出应用程序。 .. note:: @@ -285,31 +286,17 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 你已完成 ESP32 的入门！ -现在你可以尝试其他的示例工程 :idf:`examples`，或者直接开发自己的应用程序。 +现在你可以尝试其他的示例工程 :idf:`examples`，或者直接开发自己的应用程序。 更新 ESP-IDF ============= 使用 ESP-IDF 一段时间后，你可能想要进行升级来获得新的性能或者对 bug 进行修复。最简单的更新方式是删除已有的 ``esp-idf`` 文件夹然后再克隆一个，即重复 :ref:`get-started-get-esp-idf` 里的操作。 -另外一种方法是只更新有改动的部分，如果你不容易登陆 GitHub，那么这种方法比较合适。执行以下命令： :: - - cd ~/esp/esp-idf - git pull - git submodule update --init --recursive - -``git pull`` 指令是从 ESP-IDF 仓库中获取合并更新。``git submodule update --init --recursive`` 用来更新现有的子模块或拷贝新的子模块。在 GitHub 上，子模块链接到其他仓库，所以需要这个额外的指令来下载到你的电脑里。 - -如果你想使用某一版本的 ESP-IDF，比如 `v2.1` 版本，请执行以下指令： :: - - cd ~/esp - git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1 - cd esp-idf-v2.1/ - git checkout v2.1 - git submodule update --init --recursive - 然后 :doc:`add-idf_path-to-profile`，这样工具链脚本就能够知道这一版本的 ESP-IDF 的具体位置。 +另外一种方法是只更新有改动的部分。:ref:`更新步骤取决于现在用的ESP-IDF版本 `。 + 相关文档 ================= @@ -323,3 +310,6 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 eclipse-setup idf-monitor toolchain-setup-scratch + +.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ +.. _Releases page: https://github.com/espressif/esp-idf/releases