from __future__ import print_function
from __future__ import unicode_literals
-import sys, os
-import re
+import sys
+import os
import subprocess
-import shlex
# Note: If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
except KeyError:
idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), '..'))
+
def call_with_python(cmd):
# using sys.executable ensures that the scripts are called with the same Python interpreter
if os.system('{} {}'.format(sys.executable, cmd)) != 0:
raise RuntimeError('{} failed'.format(cmd))
+
# Call Doxygen to get XML files from the header files
print("Calling Doxygen to generate latest XML files")
if os.system("doxygen ../Doxyfile") != 0:
# Generate 'api_name.inc' files using the XML files by Doxygen
call_with_python('../gen-dxd.py')
+
def find_component_files(parent_dir, target_filename):
parent_dir = os.path.abspath(parent_dir)
result = []
print("List of %s: %s" % (target_filename, ", ".join(result)))
return result
+
# Generate 'kconfig.inc' file from components' Kconfig files
print("Generating kconfig.inc from kconfig contents")
kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
"--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(" ".join(kconfig_projbuilds)),
"--env", "IDF_PATH={}".format(idf_path),
"--output", "docs", kconfig_inc_path + '.in'
-]
+ ]
subprocess.check_call(confgen_args)
copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
call_with_python('../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in')
copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path)
+
# Generate version-related includes
#
# (Note: this is in a function as it needs to access configuration to get the language)
call_with_python('../gen-version-specific-includes.py {} {}'.format(app.config.language, version_tmpdir))
copy_if_modified(version_tmpdir, '{}/inc'.format(builddir))
+
# Generate toolchain download links
print("Generating toolchain download links")
base_url = 'https://dl.espressif.com/dl/'
copy_if_modified(toolchain_tmpdir, '{}/inc'.format(builddir))
# http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
-#
+#
suppress_warnings = ['image.nonlocal_uri']
# -- General configuration ------------------------------------------------
+
# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['breathe',
- 'link-roles',
- 'sphinxcontrib.blockdiag',
- 'sphinxcontrib.seqdiag',
- 'sphinxcontrib.actdiag',
- 'sphinxcontrib.nwdiag',
- 'sphinxcontrib.rackdiag',
- 'sphinxcontrib.packetdiag'
- ]
+ 'link-roles',
+ 'sphinxcontrib.blockdiag',
+ 'sphinxcontrib.seqdiag',
+ 'sphinxcontrib.actdiag',
+ 'sphinxcontrib.nwdiag',
+ 'sphinxcontrib.rackdiag',
+ 'sphinxcontrib.packetdiag'
+ ]
# Set up font for blockdiag, nwdiag, rackdiag and packetdiag
blockdiag_fontpath = '../_static/DejaVuSans.ttf'
# Doxygen regenerates files in 'xml/' directory every time,
# but we copy files to 'xml_in/' only when they change, to speed up
# incremental builds.
-breathe_projects = { "esp32-idf": "xml_in/" }
+breathe_projects = {"esp32-idf": "xml_in/"}
breathe_default_project = "esp32-idf"
# Add any paths that contain templates here, relative to this directory.
# The suffix of source filenames.
source_suffix = ['.rst', '.md']
-source_parsers = {
- '.md': 'recommonmark.parser.CommonMarkParser',
- }
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser',
+ }
# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
-#today = ''
+# today = ''
# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
+# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# The reST default role (used for this markup: `text`) to use for all
# documents.
-#default_role = None
+# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
-#add_module_names = True
+# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
-#show_authors = False
+# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
+# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
+# keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
-#html_theme_options = {}
+# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
-#html_title = None
+# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
+# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
-#html_favicon = None
+# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
-#html_extra_path = []
+# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+# html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
-#html_use_smartypants = True
+# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
-#html_additional_pages = {}
+# html_additional_pages = {}
# If false, no module index is generated.
-#html_domain_indices = True
+# html_domain_indices = True
# If false, no index is generated.
-#html_use_index = True
+# html_use_index = True
# If true, the index is split into individual pages for each letter.
-#html_split_index = False
+# html_split_index = False
# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
+# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
+# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'ReadtheDocsTemplatedoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
+ # The paper size ('letterpaper' or 'a4paper').
+ # 'papersize': 'letterpaper',
+ #
+ # The font size ('10pt', '11pt' or '12pt').
+ # 'pointsize': '10pt',
+ #
+ # Additional stuff for the LaTeX preamble.
+ # 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- ('index', 'ReadtheDocsTemplate.tex', u'Read the Docs Template Documentation',
- u'Read the Docs', 'manual'),
+ ('index', 'ReadtheDocsTemplate.tex', u'Read the Docs Template Documentation',
+ u'Read the Docs', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
-#latex_logo = None
+# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
-#latex_use_parts = False
+# latex_use_parts = False
# If true, show page references after internal links.
-#latex_show_pagerefs = False
+# latex_show_pagerefs = False
# If true, show URL addresses after external links.
-#latex_show_urls = False
+# latex_show_urls = False
# Documents to append as an appendix to all manuals.
-#latex_appendices = []
+# latex_appendices = []
# If false, no module index is generated.
-#latex_domain_indices = True
+# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
]
# If true, show URL addresses after external links.
-#man_show_urls = False
+# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'ReadtheDocsTemplate', u'Read the Docs Template Documentation',
- u'Read the Docs', 'ReadtheDocsTemplate', 'One line description of project.',
- 'Miscellaneous'),
+ ('index', 'ReadtheDocsTemplate', u'Read the Docs Template Documentation',
+ u'Read the Docs', 'ReadtheDocsTemplate', 'One line description of project.',
+ 'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
+# texinfo_appendices = []
# If false, no module index is generated.
-#texinfo_domain_indices = True
+# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
+# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
+# texinfo_no_detailmenu = False
+
# Override RTD CSS theme to introduce the theme corrections
# https://github.com/rtfd/sphinx_rtd_theme/pull/432
import re
TEMPLATES = {
- "en" : {
- "git-clone" : {
- "template" : """
+ "en": {
+ "git-clone": {
+ "template": """
To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command::
cd ~/esp
.. note::
%(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 %(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.'
- }, # zipfile
- }, # git-clone
- "version-note" : {
- "master" : """
+""",
+ "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 %(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.'
+ }, # zipfile
+ }, # git-clone
+ "version-note": {
+ "master": """
.. note::
- 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" : """
+ 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::
This is documentation for stable version %s of ESP-IDF. Other :doc:`/versions` are also available.
-"""
- ,"branch" : """
+""",
+ "branch": """
.. note::
This is documentation for %s ``%s`` of ESP-IDF. Other :doc:`/versions` are also available.
"""
- }, # version-note
- }, # en
- "zh_CN" : {
- "git-clone" : {
- "template" : """
+ }, # version-note
+ }, # en
+ "zh_CN": {
+ "git-clone": {
+ "template": """
获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库::
cd ~/esp
.. 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" : """
+""",
+ "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" : """
+ 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" : """
+""",
+ "branch": """
.. note::
这是ESP-IDF %s ``%s`` 版本的文档，还有其他版本的文档 :doc:`/versions` 供参考。
"""
- }, # version-note
- }# zh_CN
+ }, # version-note
+ } # zh_CN
}
zipfile = template["zipfile"]
if version == "master":
args = {
- "clone_args" : "",
- "extra_note" : template["master"],
- "zipfile_note" : zipfile["unstable"]
+ "clone_args": "",
+ "extra_note": template["master"],
+ "zipfile_note": zipfile["unstable"]
}
else:
args = {
- "clone_args" : "-b %s " % version,
- "extra_note" : template["branch"] % {"clone_arg" : version, "ver_type" : ver_type},
- "zipfile_note" : zipfile["stable"] if is_stable else zipfile["unstable"]
+ "clone_args": "-b %s " % version,
+ "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")
with open(out_file, "w", encoding='utf-8') as f:
print("refs:\n%s" % refs)
refs = refs.split(b"\n")
# Note: this looks for branches in 'origin' because GitLab CI doesn't check out a local branch
- branches = [ r.replace(b"refs/remotes/origin/",b"").strip() for r in refs if r.startswith(b"refs/remotes/origin/") ]
+ branches = [r.replace(b"refs/remotes/origin/",b"").strip() for r in refs if r.startswith(b"refs/remotes/origin/")]
if len(branches) == 0:
# last resort, return the commit (may happen on Gitlab CI sometimes, unclear why)
return (subprocess.check_output(["git", "rev-parse", "--short", "HEAD"]).strip(), "commit", False)
else:
return (branches[0], "branch", False) # take whatever the first branch is
+
if __name__ == "__main__":
main()
projects / esp-idf / commitdiff