granicus.if.org Git - esp-idf/blob - docs/gen-version-specific-includes.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3 #
   4 # Python script to generate ReSTructured Text .inc snippets
   5 # with version-based content for this IDF version
   6
   7 import subprocess
   8 import os
   9 import sys
  10 import re
  11
  12 TEMPLATES = {
  13     "en" : {
  14         "git-clone" : {
  15             "template" : """
  16 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::
  17
  18     cd ~/esp
  19     git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
  20
  21 ESP-IDF will be downloaded into ``~/esp/esp-idf``.
  22
  23 .. note::
  24
  25     %(extra_note)s
  26
  27 .. note::
  28
  29     %(zipfile_note)s
  30 """
  31             ,"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.'
  32             ,"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.'
  33             ,"zipfile" : {
  34                 "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.'
  35                 ,"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.'
  36                 },  # zipfile
  37             },  # git-clone
  38         "version-note" : {
  39             "master" : """
  40 .. note::
  41      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`.
  42 """
  43             ,"stable" : """
  44 .. note::
  45      This is documentation for stable version %s of ESP-IDF. Other :doc:`/versions` are also available.
  46 """
  47             ,"branch" : """
  48 .. note::
  49      This is documentation for %s ``%s`` of ESP-IDF. Other :doc:`/versions` are also available.
  50 """
  51             },  # version-note
  52     }, # en
  53     "zh_CN" : {
  54         "git-clone" : {
  55             "template" : """
  56 获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库::
  57
  58     cd ~/esp
  59     git clone %(clone_args)s--recursive https://github.com/espressif/esp-idf.git
  60
  61 ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
  62
  63 .. note::
  64
  65     %(extra_note)s
  66
  67 .. note::
  68
  69     %(zipfile_note)s
  70 """
  71             ,"master" : '此命令将克隆 master 分支，该分支保存着 ESP-IDF 的最新版本，它功能齐全，每周都会更新一些新功能并修正一些错误。'
  72             ,"branch" : '``git clone`` 命令的 ``-b %(clone_arg)s`` 选项告诉 git 从 ESP-IDF 仓库中克隆与此版本的文档对应的分支。'
  73             ,"zipfile" : {
  74                 "stable" : '作为备份，还可以从 `Releases page`_ 下载此稳定版本的 zip 文件。不要下载由 GitHub 自动生成的"源代码"的 zip 文件，它们不适用于 ESP-IDF。'
  75                 ,"unstable" : 'GitHub 中"下载 zip 文档"的功能不适用于 ESP-IDF，所以需要使用 ``git clone`` 命令。作为备份，可以在没有安装 Git 的环境中下载 `Stable version`_ 的 zip 归档文件。'
  76                 },  # zipfile
  77             },  # git-clone
  78         "version-note" : {
  79             "master" : """
  80 .. note::
  81      这是ESP-IDF master 分支（最新版本）的文档，该版本在持续开发中。还有 `Stable version`_ 的文档，以及其他版本的文档 :doc:`/versions` 供参考。
  82      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`.
  83 """
  84             ,"stable" : """
  85 .. note::
  86      这是ESP-IDF 稳定版本 %s 的文档，还有其他版本的文档 :doc:`/versions` 供参考。
  87 """
  88             ,"branch" : """
  89 .. note::
  90      这是ESP-IDF %s ``%s`` 版本的文档，还有其他版本的文档 :doc:`/versions` 供参考。
  91 """
  92             },  # version-note
  93     }# zh_CN
  94 }
  95
  96
  97 def main():
  98     if len(sys.argv) != 3:
  99         print("Usage: gen-git-clone.py <language> <output file path>")
 100         sys.exit(1)
 101
 102     language = sys.argv[1]
 103     out_dir = sys.argv[2]
 104     if not os.path.exists(out_dir):
 105         print("Creating directory %s" % out_dir)
 106         os.mkdir(out_dir)
 107
 108     template = TEMPLATES[language]
 109
 110     version, ver_type, is_stable = get_version()
 111
 112     write_git_clone_inc(template["git-clone"], out_dir, version, ver_type, is_stable)
 113     write_version_note(template["version-note"], out_dir, version, ver_type, is_stable)
 114     print("Done")
 115
 116
 117 def write_git_clone_inc(template, out_dir, version, ver_type, is_stable):
 118     zipfile = template["zipfile"]
 119     if version == "master":
 120         args = {
 121             "clone_args" : "",
 122             "extra_note" : template["master"],
 123             "zipfile_note" : zipfile["unstable"]
 124         }
 125     else:
 126         args = {
 127             "clone_args" : "-b %s " % version,
 128             "extra_note" : template["branch"] % {"clone_arg" : version, "ver_type" : ver_type},
 129             "zipfile_note" : zipfile["stable"] if is_stable else zipfile["unstable"]
 130         }
 131     out_file = os.path.join(out_dir, "git-clone.inc")
 132     with open(out_file, "w") as f:
 133         f.write(template["template"] % args)
 134     print("%s written" % out_file)
 135
 136
 137 def write_version_note(template, out_dir, version, ver_type, is_stable):
 138     if version == "master":
 139         content = template["master"]
 140     elif ver_type == "tag" and is_stable:
 141         content = template["stable"] % version
 142     else:
 143         content = template["branch"] % (ver_type, version)
 144     out_file = os.path.join(out_dir, "version-note.inc")
 145     with open(out_file, "w") as f:
 146         f.write(content)
 147     print("%s written" % out_file)
 148
 149
 150 def get_version():
 151     """
 152     Returns a tuple of (name of branch/tag, type branch/tag, is_stable)
 153     """
 154     # Trust what RTD says our version is, if it is set
 155     version = os.environ.get("READTHEDOCS_VERSION", None)
 156     if version == "latest":
 157         return ("master", "branch", False)
 158
 159     # Otherwise, use git to look for a tag
 160     try:
 161         tag = subprocess.check_output(["git", "describe", "--tags", "--exact-match"]).strip()
 162         is_stable = re.match(r"v[0-9\.]+$", tag) is not None
 163         return (tag, "tag", is_stable)
 164     except subprocess.CalledProcessError:
 165         pass
 166
 167     # No tag, look for a branch
 168     refs = subprocess.check_output(["git", "for-each-ref", "--points-at", "HEAD", "--format", "%(refname)"])
 169     print("refs:\n%s" % refs)
 170     refs = refs.split("\n")
 171     # Note: this looks for branches in 'origin' because GitLab CI doesn't check out a local branch
 172     branches = [ r.replace("refs/remotes/origin/","").strip() for r in refs if r.startswith("refs/remotes/origin/") ]
 173     if len(branches) == 0:
 174         # last resort, return the commit (may happen on Gitlab CI sometimes, unclear why)
 175         return (subprocess.check_output(["git", "rev-parse", "--short", "HEAD"]).strip(), "commit", False)
 176     if "master" in branches:
 177         return ("master", "branch", False)
 178     else:
 179         return (branches[0], "branch", False)  # take whatever the first branch is
 180
 181 if __name__ == "__main__":
 182     main()