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

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

Aperta
#778 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
bug
Lingua principale
Python
Stelle
10
Fork
32
Merge medio
23h 52m
PR unite (30g)
52

Descrizione

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

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

Inizia da docs/how-to/bundles/examples.rst e dalla definizione pubblica di //:docs_bundle, quindi riproduci il fallimento con la configurazione external-bundle e bazel run //:docs. Traccia quali file di esempio vengono esportati al di fuori di docs/. Il lavoro è completato quando sia le build standalone sia quelle external-bundle hanno esito positivo senza errori di confinamento dei percorsi.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Ambito
build-system, documentation
Tipo di issue
Bug
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
55/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.