Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: Correct Python coding style

Browse source
This commit is contained in:
Roland Dobai 2018-12-01 09:25:08 +01:00
parent eb27686416
commit b56ed1a99e
9 changed files with 157 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
.flake8
View file

@ -164,14 +164,6 @@ exclude =
components/ulp/esp32ulp_mapgen.py,
components/wifi_provisioning/python/wifi_config_pb2.py,
components/wifi_provisioning/python/wifi_constants_pb2.py,
docs/conf_common.py,
docs/en/conf.py,
docs/gen-dxd.py,
docs/gen-toolchain-links.py,
docs/gen-version-specific-includes.py,
docs/link-roles.py,
docs/local_util.py,
docs/zh_CN/conf.py,
examples/peripherals/can/can_alert_and_recovery/example_test.py,
examples/peripherals/can/can_network/example_test.py,
examples/peripherals/can/can_self_test/example_test.py,

20
docs/conf_common.py
View file

@ -16,10 +16,9 @@
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
@ -41,11 +40,13 @@ try:
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:
@ -58,6 +59,7 @@ copy_if_modified('xml/', 'xml_in/')
# 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 = []
@ -73,6 +75,7 @@ def find_component_files(parent_dir, target_filename):
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)
@ -99,6 +102,7 @@ esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(builddir)
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)
@ -108,6 +112,7 @@ def generate_version_specific_includes(app):
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/'
@ -121,6 +126,7 @@ suppress_warnings = ['image.nonlocal_uri']
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
@ -162,8 +168,7 @@ templates_path = ['_templates']
# 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.
@ -315,10 +320,10 @@ htmlhelp_basename = 'ReadtheDocsTemplatedoc'
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': '',
}
@ -388,6 +393,7 @@ texinfo_documents = [
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# Override RTD CSS theme to introduce the theme corrections
# https://github.com/rtfd/sphinx_rtd_theme/pull/432
def setup(app):

5
docs/en/conf.py
View file

@ -6,9 +6,10 @@
# Importing conf_common adds all the non-language-specific
# parts to this conf module
import sys, os
import sys
import os
sys.path.insert(0, os.path.abspath('..'))
from conf_common import *
from conf_common import * # noqa: F401, F403 - need to make available everything from common
# General information about the project.
project = u'ESP-IDF Programming Guide'

2
docs/gen-dxd.py
View file

@ -78,7 +78,7 @@ def get_doxyfile_input():
# process only lines that are not comments
if line.find("#") == -1:
# extract header file path inside components folder
m = re.search(header_file_path_prefix + "(.*\.h)", line)
m = re.search(header_file_path_prefix + "(.*\.h)", line) # noqa: W605 - regular expression
header_file_path = m.group(1)
doxyfile_INPUT += header_file_path + "\n"
# proceed reading next line

2
docs/gen-toolchain-links.py
View file

@ -10,6 +10,7 @@ from __future__ import print_function
import sys
import os
def main():
if len(sys.argv) != 4:
print("Usage: gen-toolchain-links.py <versions file> <base download URL> <output directory>")
@ -73,5 +74,6 @@ def main():
with open(os.path.join(out_dir, 'scratch-build-code.inc'), "w") as code_file:
print(scratch_build_code_linux_macos, file=code_file)
if __name__ == "__main__":
main()

52
docs/gen-version-specific-includes.py
View file

@ -30,24 +30,29 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``.
.. 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.'
""",
"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.
"""
@ -70,25 +75,27 @@ ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
.. 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 归档文件。'
""",
"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` 供参考。
"""
@ -181,5 +188,6 @@ def get_version():
else:
return (branches[0], "branch", False) # take whatever the first branch is
if __name__ == "__main__":
main()

6
docs/link-roles.py
View file

@ -7,6 +7,7 @@ import os
from docutils import nodes
from local_util import run_cmd_get_output
def get_github_rev():
path = run_cmd_get_output('git rev-parse --short HEAD')
tag = run_cmd_get_output('git describe --exact-match')
@ -16,6 +17,7 @@ def get_github_rev():
path = tag
return path
def setup(app):
rev = get_github_rev()
@ -44,9 +46,10 @@ def setup(app):
app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
def autolink(pattern):
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
m = re.search('(.*)\s*<(.*)>', text)
m = re.search('(.*)\s*<(.*)>', text) # noqa: W605 - regular expression
if m:
link_text = m.group(1)
link = m.group(2)
@ -58,6 +61,7 @@ def autolink(pattern):
return [node], []
return role
def crosslink(pattern):
def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
(language, link_text) = text.split(':')

6
docs/local_util.py
View file

@ -16,13 +16,14 @@
from __future__ import unicode_literals
from io import open
import re
import os
import shutil
def run_cmd_get_output(cmd):
return os.popen(cmd).read().strip()
def files_equal(path_1, path_2):
if not os.path.exists(path_1) or not os.path.exists(path_2):
return False
@ -34,6 +35,7 @@ def files_equal(path_1, path_2):
file_2_contents = f_2.read()
return file_1_contents == file_2_contents
def copy_file_if_modified(src_file_path, dst_file_path):
if not files_equal(src_file_path, dst_file_path):
dst_dir_name = os.path.dirname(dst_file_path)
@ -41,6 +43,7 @@ def copy_file_if_modified(src_file_path, dst_file_path):
os.makedirs(dst_dir_name)
shutil.copy(src_file_path, dst_file_path)
def copy_if_modified(src_path, dst_path):
if os.path.isfile(src_path):
copy_file_if_modified(src_path, dst_path)
@ -52,4 +55,3 @@ def copy_if_modified(src_path, dst_path):
src_file_path = os.path.join(root, src_file_name)
dst_file_path = os.path.join(dst_path + root[src_path_len:], src_file_name)
copy_file_if_modified(src_file_path, dst_file_path)

5
docs/zh_CN/conf.py
View file

@ -6,9 +6,10 @@
# Importing conf_common adds all the non-language-specific
# parts to this conf module
import sys, os
import sys
import os
sys.path.insert(0, os.path.abspath('..'))
from conf_common import *
from conf_common import * # noqa: F401, F403 - need to make available everything from common
# General information about the project.
project = u'ESP-IDF 编程指南'