esp-docs 2.4.0__tar.gz → 2.5.0__tar.gz

{esp_docs-2.4.0 → esp_docs-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esp-docs
-Version: 2.4.0
+Version: 2.5.0
 Summary: Documentation building package used at Espressif
 Home-page: https://github.com/espressif/esp-docs
 Author: Espressif

{esp_docs-2.4.0 → esp_docs-2.5.0}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "setuptools.build_meta"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "2.4.0"
+version = "2.5.0"
 tag_format = "v$version"
 version_files = [
     "setup.cfg:version",

{esp_docs-2.4.0 → esp_docs-2.5.0}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = esp-docs
-version = 2.4.0
+version = 2.5.0
 author = Espressif
 author_email = marius.vikhammer@espressif.com
 description = Documentation building package used at Espressif

{esp_docs-2.4.0 → esp_docs-2.5.0}/src/esp_docs/build_docs.py

@@ -26,6 +26,7 @@
 from __future__ import print_function
 
 import argparse
+import json
 import locale
 import math
 import multiprocessing
@@ -36,6 +37,7 @@ import subprocess
 import sys
 from pathlib import Path
 from .check_docs import check_docs, format_path_for_display, style_text
+from .modified_files import parse_modified_files_arg
 from .check_lang_switch import run_lang_linkcheck
 from esp_docs.constants import TARGETS
 
@@ -89,6 +91,8 @@ def main():
     parser.add_argument('--input-docs', '-i', nargs='+', default=[''],
                         help='List of documents to build relative to the doc base folder, i.e. the language folder. Defaults to all documents')
     parser.add_argument('--fast-build', '-f', action='store_true', help='Skips including doxygen generated APIs into the Sphinx build')
+    parser.add_argument('--modified-files', nargs='+', default=[],
+                        help='List of modified files relative to the project path, used by smart build logic')
     parser.add_argument('--skip-reqs-check', action='store_true', help='Skips checking python requirements.txt found in the current directory (deprecated)')
 
     action_parsers = parser.add_subparsers(dest='action')
@@ -103,6 +107,7 @@ def main():
     action_parsers.add_parser('lang-linkcheck', help='Check if link_to_translation directives are present in RST files included in toctrees')
 
     args = parser.parse_args()
+    args.modified_files = parse_modified_files_arg(args.modified_files)
 
     global languages
     if args.language is None:
@@ -183,6 +188,7 @@ def parallel_call(args, callback):
             build_info['builders'] = args.builders
             build_info['input_docs'] = args.input_docs
             build_info['doxyfile_dir'] = args.doxyfile_dir
+            build_info['modified_files'] = args.modified_files
             build_info['project_path'] = args.project_path
 
             entries.append(build_info)
@@ -225,6 +231,7 @@ def sphinx_call(build_info, builder):
     environ = {}
     environ.update(os.environ)
     environ['BUILDDIR'] = build_info['build_dir']
+    environ['DOCS_MODIFIED_FILES'] = json.dumps(build_info['modified_files'])
 
     args = [sys.executable, '-u', '-m', 'sphinx.cmd.build',
             '-j', str(build_info['sphinx_parallel_jobs']),

{esp_docs-2.4.0 → esp_docs-2.5.0}/src/esp_docs/conf_docs.py

@@ -325,6 +325,7 @@ def setup(app):
     app.add_config_value('docs_to_build', None, 'env')
     app.add_config_value('user_setup_callback', None, 'env')
     app.add_config_value('doc_id', None, 'env')
+    app.add_config_value('modified_files', os.environ.get('DOCS_MODIFIED_FILES', '[]'), 'env')
 
     # Breathe extension variables (depend on build_dir)
     # note: we generate into xml_in and then copy_if_modified to xml dir

{esp_docs-2.4.0 → esp_docs-2.5.0}/src/esp_docs/esp_extensions/run_doxygen.py

@@ -9,6 +9,7 @@ from io import open
 from collections import defaultdict
 from dataclasses import dataclass
 
+from ..modified_files import get_modified_files, normalize_modified_file_path
 from ..util.util import copy_if_modified
 
 ALL_KINDS = [
@@ -52,6 +53,16 @@ def find_doxygen_dir(doxyfile_dir):
         return doxyfile_dir
 
 
+def should_keep_api_reference(header_path, modified_files, fast_build):
+    if not fast_build:
+        return True
+
+    if not modified_files:
+        return False
+
+    return normalize_modified_file_path(header_path) in modified_files
+
+
 def generate_doxygen(app, defines):
 
     build_dir = app.config.build_dir
@@ -150,6 +161,7 @@ def convert_api_xml_to_inc(app, doxyfiles):
     inc_directory_path = '{}/inc'.format(build_dir)
 
     fast_build = os.environ.get('DOCS_FAST_BUILD', None)
+    modified_files = get_modified_files(app.config)
 
     if not os.path.isdir(xml_directory_path):
         raise RuntimeError('Directory {} does not exist!'.format(xml_directory_path))
@@ -161,28 +173,27 @@ def convert_api_xml_to_inc(app, doxyfiles):
 
     print("Generating 'api_name.inc' files with Doxygen directives")
     for api_path in api_paths:
-        rst_output = generate_directives(app, api_path.header_path, api_path.xml_file_path)
+        final_rst_output = generate_directives(app, api_path.header_path, api_path.xml_file_path)
+
+        # For fast builds we skip unchanged API reference includes, but still keep
+        # the ones generated from modified headers.
+        if not should_keep_api_reference(api_path.header_path, modified_files, fast_build):
+            final_rst_output = ''
 
         # Create subfolders if needed
         dir_name = os.path.dirname(api_path.inc_file_path)
         if dir_name:
             os.makedirs(dir_name, exist_ok=True)
 
+        inc_exists = os.path.isfile(api_path.inc_file_path)
         previous_rst_output = ''
-        if os.path.isfile(api_path.inc_file_path):
+        if inc_exists:
             with open(api_path.inc_file_path, 'r', encoding='utf-8') as inc_file_old:
                 previous_rst_output = inc_file_old.read()
 
-        if previous_rst_output != rst_output:
-            with open(api_path.inc_file_path, 'w', encoding='utf-8') as inc_file:
-                inc_file.write(rst_output)
-
-        # For fast builds we wipe the doxygen api documentation.
-        # Parsing this output during the sphinx build process is
-        # what takes 95% of the build time
-        if fast_build:
+        if (not inc_exists) or previous_rst_output != final_rst_output:
             with open(api_path.inc_file_path, 'w', encoding='utf-8') as inc_file:
-                inc_file.write('')
+                inc_file.write(final_rst_output)
 
 
 def get_doxyfile_input_paths(app, doxyfile_path):
@@ -215,7 +226,7 @@ def get_doxyfile_input_paths(app, doxyfile_path):
             # process only lines that are not comments
             if line.find('#') == -1:
                 # extract header file path inside project folder
-                m = re.search('\(PROJECT_PATH\)/(.*\.hp*)', line)  # noqa: W605 - regular expression
+                m = re.search(r'\(PROJECT_PATH\)/(.*\.hp*)', line)
                 if m is None:
                     raise ValueError("Doxygen input statements should be specified using $(PROJECT_PATH) env variable, instead got {}".format(line))
                 header_file_path = m.group(1)

esp_docs-2.5.0/src/esp_docs/modified_files.py

@@ -0,0 +1,53 @@
+from __future__ import unicode_literals
+
+import json
+import os
+
+
+def parse_modified_files_arg(modified_files):
+    if not modified_files:
+        return []
+
+    normalized_paths = []
+    for value in modified_files:
+        if not value:
+            continue
+
+        normalized_paths.extend(
+            path for path in value.split(';') if path
+        )
+
+    return normalized_paths
+
+
+def normalize_modified_file_path(file_path, project_path=None):
+    normalized_path = file_path
+
+    if project_path and os.path.isabs(normalized_path):
+        normalized_path = os.path.relpath(normalized_path, project_path)
+
+    normalized_path = os.path.normpath(normalized_path).replace('\\', '/')
+
+    if normalized_path == '.':
+        return ''
+
+    while normalized_path.startswith('./'):
+        normalized_path = normalized_path[2:]
+
+    return normalized_path
+
+
+def get_modified_files(config):
+    modified_files = config.modified_files
+
+    if not modified_files:
+        return set()
+
+    if isinstance(modified_files, str):
+        modified_files = json.loads(modified_files)
+
+    return {
+        normalize_modified_file_path(path, config.project_path)
+        for path in modified_files
+        if path
+    }

{esp_docs-2.4.0 → esp_docs-2.5.0}/src/esp_docs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esp-docs
-Version: 2.4.0
+Version: 2.5.0
 Summary: Documentation building package used at Espressif
 Home-page: https://github.com/espressif/esp-docs
 Author: Espressif

{esp_docs-2.4.0 → esp_docs-2.5.0}/src/esp_docs.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/esp_docs/constants.py
 src/esp_docs/deploy_docs.py
 src/esp_docs/deploy_docs_s3.py
 src/esp_docs/get_github_rev.py
+src/esp_docs/modified_files.py
 src/esp_docs/sanitize_version.py
 src/esp_docs/upload_docs_s3.py
 src/esp_docs.egg-info/PKG-INFO