docs: translate the version include script to Chinese
This commit is contained in:
Michael (XIAO Xufeng)
Angus Gratton
parent
ed8013ccc2
commit
522f9c4b4a
|
|
@ -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")
|
||||
|
|
|
|||
|
|
@ -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 <target>' where <target> is one of"
|
||||
@echo "Please use \`make <target>\' where <target> 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
|
||||
|
|
|
|||
|
|
@ -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 <windows-setup>
|
||||
Linux <linux-setup>
|
||||
Linux <linux-setup>
|
||||
MacOS <macos-setup>
|
||||
|
||||
+-------------------+-------------------+-------------------+
|
||||
|
|
@ -110,12 +112,11 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了
|
|||
|
||||
.. highlight:: bash
|
||||
|
||||
工具链（包括用于编译和构建应用程序的程序）安装完后，你还需要 ESP32 相关的 API/库。API/库在 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_ 中。要获取这些 API/库，打开一个终端，进入某个你希望存放 ESP-IDF 的目录，然后 ``git clone`` 以下指令： ::
|
||||
工具链（包括用于编译和构建应用程序的程序）安装完后，你还需要 ESP32 相关的 API/库。API/库在 `ESP-IDF 仓库 <https://github.com/espressif/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版本 <updating>`。
|
||||
|
||||
|
||||
相关文档
|
||||
=================
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue