From 3ebf41bf2bef136fd9767ac712d0c89207a9fd24 Mon Sep 17 00:00:00 2001 From: "Wolfgang Fischer (ETAS)" Date: Mon, 20 Oct 2025 09:52:17 +0200 Subject: [PATCH 1/8] Set generate without sourcecode as a default to sphinx to reduce space in the gh_pages by approx. 10%. Add option to generate sourcecode via bazel //:docs -- --sphinx_args -t source --- src/extensions/score_sphinx_bundle/__init__.py | 15 +++++++++++++++ src/incremental.py | 8 ++++++++ 2 files changed, 23 insertions(+) diff --git a/src/extensions/score_sphinx_bundle/__init__.py b/src/extensions/score_sphinx_bundle/__init__.py index 815062d5..3b362c86 100644 --- a/src/extensions/score_sphinx_bundle/__init__.py +++ b/src/extensions/score_sphinx_bundle/__init__.py @@ -10,6 +10,7 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +import logging from sphinx.application import Sphinx # Note: order matters! @@ -28,8 +29,22 @@ "sphinxcontrib.mermaid", ] +logger = logging.getLogger(__name__) + def setup(app: Sphinx) -> dict[str, object]: + + # Tag-recognition + if app.tags.has("source"): + logger.info("<< score_sphinx_bundle: 'source' tag dected - enabling source generation") + app.config.html_copy_source = True + app.config.html_show_sourcelink = True + else: + if "score_sphinx_bundle.source_code_linker" in app.config.extensions: + app.config.extensions.remove("score_sphinx_bundle.source_code_linker") + app.config.html_copy_source = False + app.config.html_show_sourcelink = False + # Global settings # Note: the "sub-extensions" also set their own config values diff --git a/src/incremental.py b/src/incremental.py index 5699c6ec..6288b4f5 100644 --- a/src/incremental.py +++ b/src/incremental.py @@ -60,6 +60,12 @@ def get_env(name: str) -> str: "Use 0 for auto detection of a free port.", default=8000, ) + parser.add_argument( + '--sphinx_args', + nargs=argparse.REMAINDER, + default=[], + help='Extra arguments to pass to sphinx-build' + ) args = parser.parse_args() if args.debug: @@ -91,6 +97,8 @@ def get_env(name: str) -> str: base_arguments.append("-A=github_version=main") base_arguments.append("-A=doc_path=docs") + base_arguments += args.sphinx_args + action = get_env("ACTION") if action == "live_preview": Path(workspace + "/_build/score_source_code_linker_cache.json").unlink( From d5944ad733daa4a53d6081bd2f69d3f50b087fbe Mon Sep 17 00:00:00 2001 From: "Wolfgang Fischer (ETAS)" Date: Mon, 20 Oct 2025 16:24:00 +0200 Subject: [PATCH 2/8] typo in message removed --- src/extensions/score_sphinx_bundle/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/extensions/score_sphinx_bundle/__init__.py b/src/extensions/score_sphinx_bundle/__init__.py index 3b362c86..828a7c4c 100644 --- a/src/extensions/score_sphinx_bundle/__init__.py +++ b/src/extensions/score_sphinx_bundle/__init__.py @@ -36,7 +36,7 @@ def setup(app: Sphinx) -> dict[str, object]: # Tag-recognition if app.tags.has("source"): - logger.info("<< score_sphinx_bundle: 'source' tag dected - enabling source generation") + logger.info("<< score_sphinx_bundle: 'source' tag detected - enabling source generation") app.config.html_copy_source = True app.config.html_show_sourcelink = True else: From 3302d027c13c0da7c12341082125defe6db04ca4 Mon Sep 17 00:00:00 2001 From: "Wolfgang Fischer (ETAS)" Date: Wed, 22 Oct 2025 14:22:26 +0200 Subject: [PATCH 3/8] to configure Sphinx a configuration mechanism is used instead of a tag which shall be used more for content --- src/extensions/score_sphinx_bundle/__init__.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/extensions/score_sphinx_bundle/__init__.py b/src/extensions/score_sphinx_bundle/__init__.py index 828a7c4c..5d476659 100644 --- a/src/extensions/score_sphinx_bundle/__init__.py +++ b/src/extensions/score_sphinx_bundle/__init__.py @@ -34,9 +34,10 @@ def setup(app: Sphinx) -> dict[str, object]: - # Tag-recognition - if app.tags.has("source"): - logger.info("<< score_sphinx_bundle: 'source' tag detected - enabling source generation") + # recognition of configuration value + app.add_config_value("enable_source_generation", False, "html") + if app.config.enable_source_generation: + logger.info("<< score_sphinx_bundle: source generation activated") app.config.html_copy_source = True app.config.html_show_sourcelink = True else: From b2b597e91f8210420444834c7b13a1fb4f989202 Mon Sep 17 00:00:00 2001 From: "Wolfgang Fischer (ETAS)" Date: Wed, 22 Oct 2025 15:01:45 +0200 Subject: [PATCH 4/8] update code --- src/extensions/score_sphinx_bundle/__init__.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/extensions/score_sphinx_bundle/__init__.py b/src/extensions/score_sphinx_bundle/__init__.py index 828a7c4c..6a288e9d 100644 --- a/src/extensions/score_sphinx_bundle/__init__.py +++ b/src/extensions/score_sphinx_bundle/__init__.py @@ -33,10 +33,10 @@ def setup(app: Sphinx) -> dict[str, object]: - - # Tag-recognition - if app.tags.has("source"): - logger.info("<< score_sphinx_bundle: 'source' tag detected - enabling source generation") + # recognition of configuration value + app.add_config_value("enable_source_generation", False, "html") + if app.config.enable_source_generation: + logger.info("<< score_sphinx_bundle: source generation activated") app.config.html_copy_source = True app.config.html_show_sourcelink = True else: From e3096f44c3bfa8f40ebbf3364a780140275f7949 Mon Sep 17 00:00:00 2001 From: "Wolfgang Fischer (ETAS)" Date: Thu, 13 Nov 2025 09:01:46 +0100 Subject: [PATCH 5/8] Remove the configuration mechanism, instead use the option 'without sourcecode' always --- src/extensions/score_sphinx_bundle/__init__.py | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/src/extensions/score_sphinx_bundle/__init__.py b/src/extensions/score_sphinx_bundle/__init__.py index 6a288e9d..1bdd361f 100644 --- a/src/extensions/score_sphinx_bundle/__init__.py +++ b/src/extensions/score_sphinx_bundle/__init__.py @@ -33,17 +33,10 @@ def setup(app: Sphinx) -> dict[str, object]: - # recognition of configuration value - app.add_config_value("enable_source_generation", False, "html") - if app.config.enable_source_generation: - logger.info("<< score_sphinx_bundle: source generation activated") - app.config.html_copy_source = True - app.config.html_show_sourcelink = True - else: - if "score_sphinx_bundle.source_code_linker" in app.config.extensions: - app.config.extensions.remove("score_sphinx_bundle.source_code_linker") - app.config.html_copy_source = False - app.config.html_show_sourcelink = False + if "score_sphinx_bundle.source_code_linker" in app.config.extensions: + app.config.extensions.remove("score_sphinx_bundle.source_code_linker") + app.config.html_copy_source = False + app.config.html_show_sourcelink = False # Global settings # Note: the "sub-extensions" also set their own config values From d89675f02b9b375e1f63b28eafaa7d3669a03741 Mon Sep 17 00:00:00 2001 From: "Wolfgang Fischer (ETAS)" Date: Thu, 13 Nov 2025 09:13:19 +0100 Subject: [PATCH 6/8] Remove extra argument --sphinx-args which is no longer needed. --- src/incremental.py | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/incremental.py b/src/incremental.py index 6288b4f5..5699c6ec 100644 --- a/src/incremental.py +++ b/src/incremental.py @@ -60,12 +60,6 @@ def get_env(name: str) -> str: "Use 0 for auto detection of a free port.", default=8000, ) - parser.add_argument( - '--sphinx_args', - nargs=argparse.REMAINDER, - default=[], - help='Extra arguments to pass to sphinx-build' - ) args = parser.parse_args() if args.debug: @@ -97,8 +91,6 @@ def get_env(name: str) -> str: base_arguments.append("-A=github_version=main") base_arguments.append("-A=doc_path=docs") - base_arguments += args.sphinx_args - action = get_env("ACTION") if action == "live_preview": Path(workspace + "/_build/score_source_code_linker_cache.json").unlink( From 163fd80a6cd5c3a3b7bf095313a037b97e3cb477 Mon Sep 17 00:00:00 2001 From: "Wolfgang Fischer (ETAS)" Date: Thu, 13 Nov 2025 09:17:13 +0100 Subject: [PATCH 7/8] Remove unused logging lines --- src/extensions/score_sphinx_bundle/__init__.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/extensions/score_sphinx_bundle/__init__.py b/src/extensions/score_sphinx_bundle/__init__.py index 1bdd361f..89a26a7e 100644 --- a/src/extensions/score_sphinx_bundle/__init__.py +++ b/src/extensions/score_sphinx_bundle/__init__.py @@ -10,7 +10,6 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -import logging from sphinx.application import Sphinx # Note: order matters! @@ -29,8 +28,6 @@ "sphinxcontrib.mermaid", ] -logger = logging.getLogger(__name__) - def setup(app: Sphinx) -> dict[str, object]: if "score_sphinx_bundle.source_code_linker" in app.config.extensions: From 1adac8c591f87ef22ef8c1d64b20fa4f08a91c17 Mon Sep 17 00:00:00 2001 From: Andreas Zwinkau Date: Wed, 10 Dec 2025 11:49:57 +0100 Subject: [PATCH 8/8] Must keep source linker --- src/extensions/score_sphinx_bundle/__init__.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/extensions/score_sphinx_bundle/__init__.py b/src/extensions/score_sphinx_bundle/__init__.py index 89a26a7e..1f40f558 100644 --- a/src/extensions/score_sphinx_bundle/__init__.py +++ b/src/extensions/score_sphinx_bundle/__init__.py @@ -30,8 +30,6 @@ def setup(app: Sphinx) -> dict[str, object]: - if "score_sphinx_bundle.source_code_linker" in app.config.extensions: - app.config.extensions.remove("score_sphinx_bundle.source_code_linker") app.config.html_copy_source = False app.config.html_show_sourcelink = False