@@ -57,6 +57,8 @@ The "Module API" proposal
5757(somewhat implemented in `tooling PR 95 <https://github.com/eclipse-score/tooling/pull/95 >`_)
5858fully relies on Bazel.
5959It is not compatible with the docs-as-code live preview as of now.
60+ `Another exploration by Useblocks <https://github.com/useblocks/bazel-drives-sphinx/tree/main >`_
61+ is available but does not cover live preview either.
6062
6163Goals
6264^^^^^
@@ -144,21 +146,37 @@ Speed ?: unclear
144146UX π‘: Live-preview requires a setup step to generate the script.
145147
146148
149+ Option D: Dual-path β keep ``:live_preview ``, add hermetic ``:docs `` build
150+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
151+
152+ Keep the existing ``bazel run :live_preview `` target unchanged (sphinx-autobuild watching ``docs/ `` on the workspace filesystem).
153+ In parallel, introduce a separate hermetic ``bazel build :docs `` target
154+ that materialises a composed source directory inside the Bazel sandbox before invoking Sphinx.
155+
156+ Effort π‘: By definition requires nearly the effort for option N and B combined.
157+
158+ Flexibility π‘: Still requires all the workarounds of option N.
159+
160+ Speed π: No slowdown.
161+
162+ UX π‘: Live-preview UX is unchanged, but risk of downstream breaks.
163+
164+
147165Evaluation
148166----------
149167
150168In order of importance, most important first.
151169
152170.. csv-table ::
153- :header: Goals, Option N, Option B
154- :widths: 2, 1, 1
171+ :header: Goals, Option N, Option B, Option D
172+ :widths: 2, 1, 1, 1
155173
156- Flexibility, π‘, π
157- Effort, π , π‘
158- Speed, π, ?
159- UX, π , π‘
174+ Flexibility, π‘, π, π‘
175+ Effort, π, π‘ , π‘
176+ Speed, π, ?, π
177+ UX, π, π‘ , π‘
160178
161- **Decision: ** Option B because Option N loses wrt flexibility
179+ **Decision: Option B ** because Option N loses wrt flexibility. Option D has no advantage over B.
162180
163181Appendix: any_folder experiment
164182-------------------------------
0 commit comments