eclipse-score / eclipse-score/docs-as-code

Public docs_bundle is not self-contained because bundle examples include files outside docs/

未关闭
#778 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
bug
主要语言
Python
星标
10
派生
32
平均合并
23 小时 52 分钟
30 天内合并 PR
52

描述

## Problem

The public `//:docs_bundle` includes `docs/how-to/bundles/examples.rst` and the nested bundle example mounts. That page uses `literalinclude` paths such as:

```rst
../../../src/tests/docs_bzl/scenarios/nested_bundles/BUILD
../../../src/tests/docs_bzl/scenarios/data_files_runfiles/BUILD
../../../src/tests/docs_bzl/scenarios/external_bundle/BUILD
```

These files are outside the `docs/` source directory. The documentation builds successfully as the standalone `docs-as-code` project, but fails when its `docs_bundle` is consumed by another Sphinx project because `sphinx-mounts` enforces path confinement for mounted documents.

## Reproduction

Consume `@score_docs_as_code//:docs_bundle` from `eclipse-score/reference_integration` with `score_docs_as_code` 8.1.0:

```python
{
"bundle": "@score_docs_as_code//:docs_bundle",
"mount_at": "process_methods_tools/docs_as_code",
"attach_to": "process_methods_tools",
}
```

Run:

```text
bazel run //:docs
```

Observed result:

```text
sphinx-mounts: mounted doc process_methods_tools/docs_as_code/how-to/bundles/examples references a file outside its bundle root: .../score_docs_as_code+/src/tests/docs_bzl/scenarios/nested_bundles/BUILD is not under .../score_docs_as_code+/docs
```

A previous closed PR, #514, attempted to add support for `literalinclude` outside `docs/`; this is the same class of problem now exposed through the public external bundle and should be resolved either by packaging the included files into the bundle or by excluding these test-fixture examples from the exported bundle.

## Expected behavior

The public `docs_bundle` should be self-contained and mountable by another Sphinx project without path-confinement errors. The standalone documentation build and the external-bundle build should exercise the same contract.

贡献指南

这个仓库没有索引到贡献指南

调研方向

Start with docs/how-to/bundles/examples.rst and the public //:docs_bundle definition, then reproduce the failure with the external-bundle configuration and bazel run //:docs. Trace which example files are exported outside docs/. Done means the standalone and external-bundle builds both succeed without path-confinement errors.

由索引模型根据 Issue 内容生成。

评估

领域
build-system, documentation
Issue 类型
缺陷
难度
4/5
预计耗时
3-5 天
活跃度
活跃
描述清晰度
基本清楚
新手友好度
55/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。