docs: Add no IDE live preview

Use sphinx-autobuild to implement live preview without requiring VSCode integration. This allows previewing on save independent of IDE. Signed-off-by: Nicolae Dicu <[email protected]>
eclipse-score · Feb 4, 2025 · 273c683 · 273c683
1 parent 4c5e976
commit 273c683
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 3 deletions.
diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ Score supports multiple methods for generating documentation, tailored to differ
 1. **Bazel-based builds** for clean, sandboxed outputs.
 2. **Incremental builds** for quick iterations during development.
 3. **IDE integration** for live previews, live warnings and even faster iterations.
+4. **IDE independent live preview** for live previews of documentation without IDE integration.
 
 ### Bazel-based Build
 
@@ -64,22 +65,46 @@ point your IDE to the .venv_docs virtual environment.
 
 Re-run //docs:ide_support if you update Sphinx extensions or other dependencies.
 
+### IDE independent live preview
+
+For a documentation live preview independent of an IDE (CLI + browser only), `sphinx-autobuild` can be used.
+
+Create venv for docs:
+
+```sh
+bazel run //docs:ide_support
+```
+
+Activate the virtual environment:
+```sh
+source .venv_docs/bin/activate
+```
+
+Run sphinx autobuild:
+```sh
+sphinx-autobuild docs/ docs/_build/html --host 0.0.0.0
+```
+
+Go to: http://localhost:8000/
+
+Now every time a doc is saved, the preview will be rebuilt.
+
 ### Testing
 
 Use the following command to run all available tests:
 
 ```
 $ bazel test //...
-``` 
+```
 
-However it's also  possible to run specific tests or set of tests. 
+However it's also  possible to run specific tests or set of tests.
 
 To run all tests of a certain language use the command below, here an example for python.
 ```
 $ bazel query 'kind(py.*, tests(//...))' | xargs bazel tests
 ```
 
-Grouping of tests via tags is also supported: 
+Grouping of tests via tags is also supported:
 ```
 $ bazel test --test_tag_filters=docs-build
 ```

diff --git a/docs/_tooling/sphinx_extensions/BUILD b/docs/_tooling/sphinx_extensions/BUILD
@@ -28,6 +28,7 @@ py_library(
     deps = [
         requirement("sphinx"),
         requirement("sphinx-needs"),
+        requirement("sphinx-design"),
         requirement("sphinxcontrib-plantuml"),
         "//docs:score_metamodel",
     ],

diff --git a/docs/_tooling/sphinx_extensions/requirements.in b/docs/_tooling/sphinx_extensions/requirements.in
@@ -3,3 +3,4 @@
 Sphinx==8.1.3
 sphinx-needs==4.1.0
 sphinxcontrib-plantuml==0.30
+sphinx-autobuild==2024.10.3