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

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

Đang mở
#778 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
bug
Ngôn ngữ chính
Python
Star
10
Fork
32
Merge trung bình
23 giờ 52 phút
Pull request đã merge (30 ngày)
52

Mô tả

## 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.

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Lĩnh vực
build-system, documentation
Loại issue
Lỗi
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Sôi nổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
55/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.