From 6d665b6e10c40294949d7afccc94a5dc981fc3cc Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Wed, 10 Aug 2022 11:24:30 +0800 Subject: [PATCH 1/3] deploy: fix symlinking failing if git commit ID differed in number of digits Git repos could use different number of digits to describe a commit dependning on if there is a collision. Fix symlinking to be indepent on the ID used. --- .gitlab-ci.yml | 3 +- src/esp_docs/deploy_docs.py | 4 +- .../_build_deploy/en/esp32/html/index.html | 0 ...p-idf-en-v5.1-dev-50-g790aa40c38-esp32.pdf | Bin .../_build_deploy/zh_CN/esp32/html/index.html | 0 ...df-zh_CN-v5.1-dev-50-g790aa40c38-esp32.pdf | Bin test/unit_tests/test_deploy.py | 90 ++++++++++++++++++ 7 files changed, 95 insertions(+), 2 deletions(-) create mode 100644 test/unit_tests/_build_deploy/en/esp32/html/index.html create mode 100644 test/unit_tests/_build_deploy/en/esp32/latex/build/esp-idf-en-v5.1-dev-50-g790aa40c38-esp32.pdf create mode 100644 test/unit_tests/_build_deploy/zh_CN/esp32/html/index.html create mode 100644 test/unit_tests/_build_deploy/zh_CN/esp32/latex/build/esp-idf-zh_CN-v5.1-dev-50-g790aa40c38-esp32.pdf create mode 100644 test/unit_tests/test_deploy.py diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 63d9136..ea61e43 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -46,7 +46,7 @@ check_python_style: script: - python -m flake8 --config=$ESP_DOCS_PATH/.flake8 $ESP_DOCS_PATH -test_extensions_ut: +test_uts: stage: test image: $ESP_DOCS_ENV_IMAGE extends: @@ -55,6 +55,7 @@ test_extensions_ut: - cd test/unit_tests - python test_docs.py - python test_esp_extensions.py + - python test_deploy.py test_builds: stage: test diff --git a/src/esp_docs/deploy_docs.py b/src/esp_docs/deploy_docs.py index a7f51b1..c2b9fce 100755 --- a/src/esp_docs/deploy_docs.py +++ b/src/esp_docs/deploy_docs.py @@ -203,7 +203,9 @@ def create_and_add_symlinks(version, git_ver, pdfs): symlinks = [] if 'stable' in version or 'latest' in version: for pdf_path in pdfs: - symlink_path = pdf_path.replace(git_ver, version) + # Sub the version info, file name is {language}-{version}-{target}.pdf + symlink_path = re.sub(r'(en-|zh_CN-)(.*?)(-esp[\w\d]*?\.pdf)', r'\1' + version + r'\3', pdf_path) + os.symlink(pdf_path, symlink_path) symlinks.append(symlink_path) diff --git a/test/unit_tests/_build_deploy/en/esp32/html/index.html b/test/unit_tests/_build_deploy/en/esp32/html/index.html new file mode 100644 index 0000000..e69de29 diff --git a/test/unit_tests/_build_deploy/en/esp32/latex/build/esp-idf-en-v5.1-dev-50-g790aa40c38-esp32.pdf b/test/unit_tests/_build_deploy/en/esp32/latex/build/esp-idf-en-v5.1-dev-50-g790aa40c38-esp32.pdf new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/test/unit_tests/_build_deploy/zh_CN/esp32/html/index.html b/test/unit_tests/_build_deploy/zh_CN/esp32/html/index.html new file mode 100644 index 0000000..e69de29 diff --git a/test/unit_tests/_build_deploy/zh_CN/esp32/latex/build/esp-idf-zh_CN-v5.1-dev-50-g790aa40c38-esp32.pdf b/test/unit_tests/_build_deploy/zh_CN/esp32/latex/build/esp-idf-zh_CN-v5.1-dev-50-g790aa40c38-esp32.pdf new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/test/unit_tests/test_deploy.py b/test/unit_tests/test_deploy.py new file mode 100644 index 0000000..5d844dc --- /dev/null +++ b/test/unit_tests/test_deploy.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 + +import unittest +import tempfile +import tarfile + +from distutils.dir_util import copy_tree +from string import Template +from esp_docs.deploy_docs import build_doc_tarball + + +class TestBuildTarball(unittest.TestCase): + BUILD_DIR_TEMPLATE_PATH = '_build_deploy' + PDF_NAME_TEMPLATE = Template('esp-idf-$lang-$ver-esp32.pdf') + VERSION = 'v5.1-dev-50-g790aa40c38' + + LANGUAGES = ['en', 'zh_CN'] + + def setUp(self): + self.temp_dir = tempfile.TemporaryDirectory() + + copy_tree(self.BUILD_DIR_TEMPLATE_PATH, self.temp_dir.name) + + def tearDown(self): + self.temp_dir.cleanup() + + def check_file_exists(self, tarball_path, file_names): + with tarfile.open(tarball_path) as f: + output = f.getnames() + for name in file_names: + self.assertTrue(any(name in o for o in output)) + + def test_build_tarball_tag(self): + version_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver=self.VERSION, lang=lang) for lang in self.LANGUAGES] + tarball_path, _ = build_doc_tarball('v4.1.0', None, self.temp_dir.name) + + self.check_file_exists(tarball_path, version_pdfs) + + def test_build_tarball_latest(self): + latest_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver='latest', lang=lang) for lang in self.LANGUAGES] + version_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver=self.VERSION, lang=lang) for lang in self.LANGUAGES] + tarball_path, _ = build_doc_tarball('latest', self.VERSION, self.temp_dir.name) + + self.check_file_exists(tarball_path, version_pdfs) + self.check_file_exists(tarball_path, latest_pdfs) + + def test_build_tarball_stable(self): + stable_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver='stable', lang=lang) for lang in self.LANGUAGES] + version_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver=self.VERSION, lang=lang) for lang in self.LANGUAGES] + tarball_path, _ = build_doc_tarball('stable', self.VERSION, self.temp_dir.name) + + self.check_file_exists(tarball_path, version_pdfs) + self.check_file_exists(tarball_path, stable_pdfs) + + # Different git repos using different numbers of digits for a commit ID + # depending on how many is needed for a unique description + # Check symlink succeeds even if they dont fully match + def test_build_tarball_latest_short_sha1(self): + latest_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver='latest', lang=lang) for lang in self.LANGUAGES] + version_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver=self.VERSION, lang=lang) for lang in self.LANGUAGES] + + version_short_sha1 = self.VERSION[:-1] + tarball_path, _ = build_doc_tarball('latest', version_short_sha1, self.temp_dir.name) + + self.check_file_exists(tarball_path, version_pdfs) + self.check_file_exists(tarball_path, latest_pdfs) + + def test_build_tarball_latest_long_sha1(self): + latest_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver='latest', lang=lang) for lang in self.LANGUAGES] + version_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver=self.VERSION, lang=lang) for lang in self.LANGUAGES] + + version_long_sha1 = self.VERSION + '5' + tarball_path, _ = build_doc_tarball('latest', version_long_sha1, self.temp_dir.name) + + self.check_file_exists(tarball_path, version_pdfs) + self.check_file_exists(tarball_path, latest_pdfs) + + def test_build_tarball_latest_random_sha(self): + latest_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver='latest', lang=lang) for lang in self.LANGUAGES] + version_pdfs = [self.PDF_NAME_TEMPLATE.substitute(ver=self.VERSION, lang=lang) for lang in self.LANGUAGES] + + version_long_sha1 = 'ra1n-dom-ID' + tarball_path, _ = build_doc_tarball('latest', version_long_sha1, self.temp_dir.name) + + self.check_file_exists(tarball_path, version_pdfs) + self.check_file_exists(tarball_path, latest_pdfs) + + +if __name__ == '__main__': + unittest.main() From 35bbb46b25661cc5ab8b77ec101f7ac2dbfce43c Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Wed, 10 Aug 2022 11:31:55 +0800 Subject: [PATCH 2/3] Add links to esp32c2 TRM/datasheet --- src/esp_docs/esp_extensions/format_esp_target.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/esp_docs/esp_extensions/format_esp_target.py b/src/esp_docs/esp_extensions/format_esp_target.py index 6910606..7ca715f 100644 --- a/src/esp_docs/esp_extensions/format_esp_target.py +++ b/src/esp_docs/esp_extensions/format_esp_target.py @@ -76,7 +76,7 @@ class StringSubstituter: 'esp32c3': 'https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_en.pdf', 'esp32s3': 'https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf', 'esp32h2': '#', - 'esp32c2': '#'} + 'esp32c2': 'https://www.espressif.com/sites/default/files/documentation/esp8684_technical_reference_manual_en.pdf'} TRM_CN_URL = {'esp8266': 'https://www.espressif.com/sites/default/files/documentation/esp8266-technical_reference_cn.pdf', 'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_cn.pdf', @@ -84,7 +84,7 @@ class StringSubstituter: 'esp32c3': 'https://www.espressif.com/sites/default/files/documentation/esp32-c3_technical_reference_manual_cn.pdf', 'esp32s3': 'https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_cn.pdf', 'esp32h2': '#', - 'esp32c2': '#'} + 'esp32c2': 'https://www.espressif.com/sites/default/files/documentation/esp8684_technical_reference_manual_cn.pdf'} DATASHEET_EN_URL = {'esp8266': 'https://www.espressif.com/sites/default/files/documentation/0a-esp8266ex_datasheet_en.pdf', 'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf', @@ -92,7 +92,7 @@ class StringSubstituter: 'esp32c3': 'https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf', 'esp32s3': 'https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf', 'esp32h2': '#', - 'esp32c2': '#'} + 'esp32c2': 'https://www.espressif.com/sites/default/files/documentation/esp8684_datasheet_en.pdf'} DATASHEET_CN_URL = {'esp8266': 'https://www.espressif.com/sites/default/files/documentation/0a-esp8266ex_datasheet_cn.pdf', 'esp32': 'https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_cn.pdf', @@ -100,7 +100,7 @@ class StringSubstituter: 'esp32c3': 'https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_cn.pdf', 'esp32s3': 'https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_cn.pdf', 'esp32h2': '#', - 'esp32c2': '#'} + 'esp32c2': 'https://www.espressif.com/sites/default/files/documentation/esp8684_datasheet_cn.pdf'} RE_PATTERN = re.compile(r'^\s*{IDF_TARGET_(\w+?):(.+?)}', re.MULTILINE) From 3b9fa826d5b547d93d29246c315921f88fac231e Mon Sep 17 00:00:00 2001 From: Marius Vikhammer Date: Wed, 10 Aug 2022 11:43:57 +0800 Subject: [PATCH 3/3] Bump version to 1.2.1 --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index 6ca9c7c..bec2ff1 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = esp-docs -version = 1.2.0 +version = 1.2.1 author = Espressif author_email = marius.vikhammer@espressif.com description = Documentation building package used at Espressif