From acc41a2a7f8eb35c52154ea53c436a8b9d49e9d2 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Thu, 3 Sep 2026 02:04:18 +0200 Subject: [PATCH 1/2] feat: support custom generated bundle entry documents --- default_conf.py.tpl | 6 +++++- docs.bzl | 7 +++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/default_conf.py.tpl b/default_conf.py.tpl index d7455cbb2..026d84720 100644 --- a/default_conf.py.tpl +++ b/default_conf.py.tpl @@ -10,13 +10,17 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -# Default Sphinx configuration emitted by the ``docs()`` macro. +# Default Sphinx configuration emitted by the ``docs()`` and +# ``docs_bundle()`` macros. # SCORE Docs-as-Code owns these baseline settings. Projects needing further # Sphinx configuration can provide their own conf.py instead. project = {PROJECT} project_url = {PROJECT_URL} version = "0.0.0" +# ``docs_bundle(entry_doc = ...)`` may use a non-index entry page. The regular +# project-level docs() build uses the default value, ``index``. +master_doc = {ENTRY_DOC} # Allow feature IDs that use the Bazel module name without its first # underscore-separated prefix (for example, ``score_docs_as_code`` becomes diff --git a/docs.bzl b/docs.bzl index 46cb7622d..001820da3 100644 --- a/docs.bzl +++ b/docs.bzl @@ -75,6 +75,11 @@ def _module_name_without_prefix(): return module_name.split("_", 1)[-1] def _generated_conf_impl(ctx): + """Generate a Sphinx config at the source-root path expected by sphinxdocs. + + ``entry_doc`` determines which document Sphinx treats as the project root + when a bundle's entry page is not named ``index``. + """ output = ctx.actions.declare_file(ctx.attr.output_path) ctx.actions.expand_template( template = ctx.file.template, @@ -83,6 +88,7 @@ def _generated_conf_impl(ctx): "{PROJECT}": repr(ctx.attr.project), "{PROJECT_URL}": repr(ctx.attr.project_url), "{REQUIRED_IN_ID}": repr([ctx.attr.required_in_id]) if ctx.attr.required_in_id else "[]", + "{ENTRY_DOC}": repr(ctx.attr.entry_doc), }, ) return [DefaultInfo(files = depset([output]))] @@ -93,6 +99,7 @@ _generated_conf = rule( "project": attr.string(mandatory = True), "project_url": attr.string(mandatory = True), "required_in_id": attr.string(mandatory = True), + "entry_doc": attr.string(default = "index"), "output_path": attr.string(mandatory = True), "template": attr.label( allow_single_file = True, From 0e43a796628a6cd9ef32607750e84b202be16be5 Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Thu, 3 Sep 2026 11:02:16 +0200 Subject: [PATCH 2/2] fix: keep bundle entries separate from root config --- default_conf.py.tpl | 6 +----- docs.bzl | 7 ------- 2 files changed, 1 insertion(+), 12 deletions(-) diff --git a/default_conf.py.tpl b/default_conf.py.tpl index 026d84720..d7455cbb2 100644 --- a/default_conf.py.tpl +++ b/default_conf.py.tpl @@ -10,17 +10,13 @@ # # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -# Default Sphinx configuration emitted by the ``docs()`` and -# ``docs_bundle()`` macros. +# Default Sphinx configuration emitted by the ``docs()`` macro. # SCORE Docs-as-Code owns these baseline settings. Projects needing further # Sphinx configuration can provide their own conf.py instead. project = {PROJECT} project_url = {PROJECT_URL} version = "0.0.0" -# ``docs_bundle(entry_doc = ...)`` may use a non-index entry page. The regular -# project-level docs() build uses the default value, ``index``. -master_doc = {ENTRY_DOC} # Allow feature IDs that use the Bazel module name without its first # underscore-separated prefix (for example, ``score_docs_as_code`` becomes diff --git a/docs.bzl b/docs.bzl index 001820da3..46cb7622d 100644 --- a/docs.bzl +++ b/docs.bzl @@ -75,11 +75,6 @@ def _module_name_without_prefix(): return module_name.split("_", 1)[-1] def _generated_conf_impl(ctx): - """Generate a Sphinx config at the source-root path expected by sphinxdocs. - - ``entry_doc`` determines which document Sphinx treats as the project root - when a bundle's entry page is not named ``index``. - """ output = ctx.actions.declare_file(ctx.attr.output_path) ctx.actions.expand_template( template = ctx.file.template, @@ -88,7 +83,6 @@ def _generated_conf_impl(ctx): "{PROJECT}": repr(ctx.attr.project), "{PROJECT_URL}": repr(ctx.attr.project_url), "{REQUIRED_IN_ID}": repr([ctx.attr.required_in_id]) if ctx.attr.required_in_id else "[]", - "{ENTRY_DOC}": repr(ctx.attr.entry_doc), }, ) return [DefaultInfo(files = depset([output]))] @@ -99,7 +93,6 @@ _generated_conf = rule( "project": attr.string(mandatory = True), "project_url": attr.string(mandatory = True), "required_in_id": attr.string(mandatory = True), - "entry_doc": attr.string(default = "index"), "output_path": attr.string(mandatory = True), "template": attr.label( allow_single_file = True,