Skip to content

Commit 5cd1ef9

Browse files
committed
Add option D
1 parent 0741388 commit 5cd1ef9

1 file changed

Lines changed: 25 additions & 7 deletions

File tree

β€Ždocs/design_decisions/DR-008-infra.rstβ€Ž

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,8 @@ The "Module API" proposal
5757
(somewhat implemented in `tooling PR 95 <https://github.com/eclipse-score/tooling/pull/95>`_)
5858
fully relies on Bazel.
5959
It 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

6163
Goals
6264
^^^^^
@@ -144,21 +146,37 @@ Speed ?: unclear
144146
UX 😑: 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+
147165
Evaluation
148166
----------
149167

150168
In 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

163181
Appendix: any_folder experiment
164182
-------------------------------

0 commit comments

Comments
Β (0)