Merge branch 'bugfix/deploy_commit_sha1' into 'master'

deploy: fix symlinking failing if git commit ID differed in number of digits

See merge request espressif/esp-docs!36

.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

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = esp-docs
-version = 1.2.0
+version = 1.2.1
 author = Espressif
 author_email = [email protected]
 description = Documentation building package used at Espressif

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)
 

src/esp_docs/esp_extensions/format_esp_target.py

@@ -76,31 +76,31 @@ 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',
                   'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_cn.pdf',
                   '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',
                         'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf',
                         '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',
                         'esp32s2': 'https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_cn.pdf',
                         '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)
 

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()