Full refactor of the docs

.readthedocs.yaml

@@ -13,6 +13,20 @@ build:
     # nodejs: "20"
     # rust: "1.70"
     # golang: "1.20"
+  apt_packages:
+    - opam
+    - build-essential
+    - m4
+    - libev-dev
+  jobs:
+    pre_build:
+      # Sandboxing must be disabled in Docker
+      - opam --version
+      - opam init --disable-sandboxing -y
+      - opam install --deps-only -y .
+      - opam exec dune -- build --profile release docs/doc-repl/main.js
+      - mkdir -p _static
+      - cp docs/doc-repl/main.js docs/_static/main.js
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

docs/Makefile

@@ -12,7 +12,19 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile _static/main.js _static/cdl.html
+
+html: _static/main.js _static/cdl.html
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+_static/main.js:
+	@opam exec -- dune build --profile release doc-repl/main.js
+	@cp doc-repl/main.js _static/main.js
+
+_static/cdl.html:
+	@opam exec -- dune build --profile release @../example/cdl/examples
+	@mkdir -p extra_html
+	@cp ../example/cdl/cdl.html extra_html/cdl.html
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/_ext/slipshowexample.py

@@ -0,0 +1,60 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+
+class slipshow_example_node(nodes.Element):
+    pass
+
+
+class SlipshowExampleDirective(Directive):
+    has_content = True
+    option_spec = {
+        "visible": directives.unchanged,
+        "dimension": directives.unchanged,
+    }
+    def run(self):
+        raw_text = "\n".join(self.content)
+        node = slipshow_example_node()
+        node['raw_text'] = raw_text
+        node['visible'] = self.options.get("visible", "both")
+        node['dimension'] = self.options.get("dimension", "")
+        return [node]
+
+def visit_slipshow_example_node_html(self, node):
+    match node['visible']:
+        case "both":
+            mode = "show-both"
+        case "editor":
+            mode = "show-editor"
+        case "presentation":
+            mode = "show-presentation"
+        case _:
+            mode = "show-both"
+    self.body.append(f"""
+<div dimension="{node['dimension']}" class="running-example {node['visible']}">
+  <div class="entry {mode}">
+    <div class="tabs">
+      <div class="editor-button">Editor</div>
+      <div class="pres-button">Presentation</div>
+      <div class="both-button">Both</div>
+      <div class="fullscreen-button">⛶</div>
+    </div>
+    <div class="editor-preview-container">
+      <div class="editor"></div>
+      <div class="preview"></div>
+    </div>
+    <div class="source" style="display:none">""")
+    # Write raw, *escaped* text so it appears exactly as typed
+    self.body.append(self.encode(node['raw_text']))
+    self.body.append('</div></div></div>')
+
+def depart_slipshow_example_node_html(self, node):
+    pass
+
+def setup(app):
+    app.add_node(
+        slipshow_example_node,
+        html=(visit_slipshow_example_node_html,
+              depart_slipshow_example_node_html),
+    )
+    app.add_directive("slipshow-example", SlipshowExampleDirective)
+    return {"version": "0.1"}

docs/_static/dune

@@ -0,0 +1,4 @@
+(rule
+ (mode promote)
+ (action
+  (copy ../doc-repl/main.bc.js main.js)))

docs/_static/style.css

@@ -0,0 +1,100 @@
+.right-panel1.active_panel, .right-panel2.active_panel {
+  z-index: 1;
+}
+.right-panel1, .right-panel2 {
+    z-index: 0;
+    width:100%;
+    position:absolute;
+    top:0;
+    bottom:0;
+    left:0;
+    right:0;
+    border:0;
+}
+
+.preview {
+    position: relative;
+}
+.entry {
+    display: flex;
+    flex-direction: column;
+}
+/* .entry > * { */
+/*     width: 50%; */
+/* } */
+/* The iframes need to be absolutely positioned so their height and width need
+   to be manually set */
+.entry .preview, .entry .preview > * {
+    height:500px;
+}
+.running-example {
+  margin-top: 24px;
+  margin-bottom: 24px;
+  padding: 0px;
+  border: 6px solid #2980b9;
+  border-radius: 12px;
+}
+.editor {
+  border-bottom: 3px solid #2980b9;
+}
+.cm-content {
+    font-size: 13px;
+}
+.tabs {
+  display: flex;
+  justify-content: space-around;
+}
+.tabs > * {
+  flex-grow: 1;
+  text-align: center;
+  border: 1px solid purple;
+  background: lightgray;
+  cursor: pointer;
+}
+
+.entry .editor, .entry .preview {
+  position: absolute;
+  opacity: 0;
+  width: 100%;
+  pointer-events: none;
+}
+.entry.show-presentation .preview,
+.entry.show-editor .editor,
+.entry.show-both .preview,
+.entry.show-both .editor {
+  opacity: 1;
+  position: relative;
+  pointer-events: all;
+}
+
+.show-editor       > .tabs > .editor-button,
+.show-presentation > .tabs > .pres-button,
+.show-both         > .tabs > .both-button {
+    background: aliceblue;
+}
+.running-example.fullscreen {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  margin: 0;
+}
+.running-example.fullscreen .editor-preview-container {
+  display:flex;
+  height: 100%;
+}
+.running-example.fullscreen .editor {
+  background: #282c34;
+  height: 100%;
+  overflow: auto;
+}
+.running-example.fullscreen .entry {
+  height: 100%;
+}
+.fullscreen .entry .preview, .fullscreen .entry .preview > * {
+  height: 100%;
+}
+.running-example .fullscreen-button {
+  flex-grow: 0;
+  padding-left: 20px;
+  padding-right: 20px;
+}

docs/actions-api.rst

@@ -0,0 +1,187 @@
+=======
+Actions
+=======
+
+An action consists of a name, a set of possible arguments, and an effect. In this page, we describe all possible actions.
+
+Inserting an action in the presentation is done by adding an attribute with the name of the action.
+
+.. code-block::
+
+   Some content.
+
+   {center}
+
+   Some other content.
+
+The effect might be different when the attribute is attached to an element.
+
+.. code-block::
+
+   Some content.
+
+   {center}
+   Some other content.
+
+Arguments can be added to an action. In this case, the attribute is a key-value attribute, the key being the name of the action, and the value containing the arguments.
+
+.. code-block::
+
+   {#one}
+   Some content.
+
+   {center=one}
+
+   Some other content.
+
+An action can have two kind of arguments: named arguments, and positional ones. Named argument are of the form ``~argument-name:value`` and positional are given as-is. The list of arguments is space-separated.
+
+.. code-block::
+
+   {#one}
+   Some content.
+
+   {center="~duration:2 ~margin:10 one"}
+
+   Some other content.
+
+It is possible to have multiple actions in a single attribute. They will be executed at the same step.
+
+.. code-block::
+
+   {#one}
+   Some content.
+
+   {center="~duration:2 ~margin:10 one" reveal="two three"}
+
+   {#two .unrevealed}
+   Some other content.
+
+   {#three .unrevealed}
+   Some more content.
+
+.. contents:: Actions table of content
+   :local:
+
+Pause attributes
+----------------
+
+``pause``
+
+  The pause attribute tells the slipshow engine to pause the text rendering
+  here. This element and every element after (but inside the "pause block") that
+  in the document will be hidden.
+
+  When a ``pause`` action is executed, the initially hidden text is displayed.
+
+``pause-block``
+  The ``pause-block`` attribute tells the slipshow engine that pauses inside it should not hide content outside of it.
+
+  Example:
+
+  .. code-block:: markdown
+
+     A
+
+     {pause-block}
+     > B
+     >
+     > {pause}
+     >
+     > C
+     >
+     > {pause}
+     >
+     > D
+
+     E
+
+  will initially display A, B and E, then going a step further will additionally display C, and another step will display D.
+
+``step``
+  Introduces a no-op step in the slip it's in. Useful to exit entered slips.
+
+Moving the window
+-----------------
+
+``down``
+  Moves the screen vertically until the element is at the bottom of the screen.
+
+  Accepts ``~duration:FLOAT`` and ``margin:INT``.
+
+``up``
+  Moves the screen vertically until the element is at the top of the screen.
+
+  Accepts ``~duration:FLOAT`` and ``margin:INT``.
+
+``center``
+  Moves the screen vertically until the element is centered.
+
+  Accepts ``~duration:FLOAT`` and ``margin:INT``.
+
+``scroll``
+  Moves the screen vertically until the element is entirely visible on screen, if possible.
+
+  Accepts ``~duration:FLOAT`` and ``margin:INT``.
+
+``focus``
+  Focus on the element by zooming on it. Possible to specify multiple ids.
+
+  Accepts ``~duration:FLOAT`` and ``margin:INT``.
+
+``unfocus``
+  Unfocus by going back to the last position before a focus.
+
+Changing visibility
+-------------------
+
+``static``
+  Make the element ``static``. By "static" we mean the css styling ``position:static; visibility:visible`` will be applied. Possible to specify multiple ids.
+
+``unstatic``
+  Make the element ``unstatic``. By "unstatic" we mean the css styling ``position:absolute; visibility:hidden`` will be applied. Possible to specify multiple ids.
+
+``reveal``
+  Reveal the element. By "revealing" we mean the css styling ``opacity:1`` will be applied.  Possible to specify multiple ids.
+
+``unreveal``
+  Hide the element. By "unrevealing" we mean the css styling ``opacity:0`` will be applied.  Possible to specify multiple ids.
+
+Drawing actions
+---------------
+
+``draw``
+  Replay the drawing. Possible to specify multiple ids. See :ref:`Record and replay drawings`.
+
+``clear``
+  Clear the drawing. Possible to specify multiple ids.
+
+Carousels
+---------
+
+``change-page``
+  Changes the current page of a carousel or pdf. Takes as input the id of the carousel/pdf.
+
+  Also takes a ``~n:"<pages>"`` argument, which allows to specify the list of pages changes to do, by absolute number (e.g. ``4``), relative number (e.g. ``+1``, ``-2``), range (``3-10`` or ``5-3``), or ``all`` which displays one by one the page until completion. Default for ``~n`` is ``+1``.
+
+  For instance, ``{change-page='~n:"2-4 6-4 7 -1 +2 all"'}`` will change pages to ``2``, ``3``, ``4``, ``6``, ``5``, ``4``, ``7``, ``6``, ``8`` and then all further pages that the pdf/carousel contains. It will always initially start with page 1.
+
+Speaker notes
+-------------
+
+``speaker-note``
+  Hides the targeted element (either with given ID, or self). When the action is executed, send the targeted element to the "Notes" section of the speaker notes (that you can open with ``s``).
+
+Medias
+------
+
+``play-media``
+  Play the media (audio or video). The associated element/target id(s) need to be a video element: a ``![](path)`` where path is recognized as a video or audio. Possible to specify multiple ids.
+
+  Pay attention that browsers will prevent the playing if they consider that the user has not "interacted" with the page yet, in an effort to forbid spam "autoplay" of medias. Interact with the page (e.g. by clicking anywhere on it) to make sure it'll work.
+
+Custom script
+-------------
+
+``exec``
+  Execute the slipscript. Possible to specify multiple ids.