Merge pull request #634 from Gencaster/tutorial

add tutorial
Gencaster · Dec 5, 2023 · 50759f7 · 50759f7
2 parents 539f313 + 1f1eebf
commit 50759f7
Show file tree

Hide file tree

Showing 31 changed files with 1,060 additions and 188 deletions.
diff --git a/caster-back/gencaster/schema.py b/caster-back/gencaster/schema.py
@@ -1,4 +1,6 @@
 """
+.. _schema:
+
 Schema
 ======
 

diff --git a/caster-back/story_graph/__init__.py b/caster-back/story_graph/__init__.py
@@ -10,7 +10,7 @@
 Graph
 -----
 
-.. figure:: ../../graphs/story_graph.png
+.. figure:: ../graphs/story_graph.svg
 
     Model graph for the story graph app.
 

diff --git a/caster-back/story_graph/models.py b/caster-back/story_graph/models.py
@@ -35,6 +35,31 @@ class Graph(models.Model):
     """
 
     class StreamAssignmentPolicy(models.TextChoices):
+        """
+        Each graph can handle different "connection" mechanisms when a listener
+        accesses a graph.
+
+        The implementation of each policy is defined in :class:`~story_graph.engine.Engine`.
+
+        .. list-table::
+            :header-rows: 1
+
+            * - StreamAssignmentPolicy
+              - Comment
+            * - `ONE_GRAPH_ONE_STREAM`
+              - All users share the same stream.
+                When the first user visits a graph, a new stream will be set up.
+                Any following user visiting the same story graph stream will be
+                "redirected" to the same stream as long as there is still *any*
+                user listening to the graph.
+                All users still execute the story graph from the beginning.
+            * - `ONE_USER_ONE_STREAM`
+              - Upon connection, each user will obtain a new and exclusive stream
+                and the graph will be executed upon the stream.
+            * - `DEACTIVATE`
+              - Non functional, for administrative work.
+        """
+
         ONE_GRAPH_ONE_STREAM = "one_graph_one_stream", _(
             "Each graph has only one stream"
         )

diff --git a/caster-back/stream/__init__.py b/caster-back/stream/__init__.py
@@ -8,7 +8,7 @@
 Graph
 -----
 
-.. figure:: ../../graphs/stream.png
+.. figure:: ../graphs/stream.svg
 
     Model graph for the stream app.
 

diff --git a/docs/Makefile b/docs/Makefile
@@ -17,9 +17,9 @@ help:
 build-graphs: export DJANGO_SETTINGS_MODULE=gencaster.settings.test
 build-graphs:
 	echo "Start building model graph images"
-	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/stream.png stream
-	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/story_graph.png story_graph
-	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/global.png stream story_graph
+	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/stream.svg stream
+	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/story_graph.svg story_graph
+	cd ../caster-back && python manage.py graph_models --pydot -g -o ../docs/graphs/global.svg stream story_graph
 	echo "Finished building model graph images"
 
 # Catch-all target: route all unknown targets to Sphinx using the new

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -48,8 +48,20 @@ html[data-theme='light'] a {
     color: var(--blue) !important
 }
 
+html[data-theme='dark'] {
+    --blue: #fff !important;
+}
+
 /* {--background-color: #212a2e;--text-color: #F7F8F8;--link-color: #828fff;} */
 
 .sig-name.descname .pre {
     background-color: var(--green);
 }
+
+.py.method {
+    margin-top: 25px;
+}
+
+.py.class {
+    margin-top: 50px;
+}
diff --git a/docs/back/api/index.rst b/docs/back/api/index.rst
diff --git a/docs/back/api/gencaster.rst → docs/back/gencaster.rst b/docs/back/api/gencaster.rst → docs/back/gencaster.rst
diff --git a/docs/back/graphql.rst b/docs/back/graphql.rst
diff --git a/docs/back/index.rst b/docs/back/index.rst
@@ -14,16 +14,15 @@ The communication with *caster-sound*, the sound generating and streaming servic
 Global model graph
 ------------------
 
-.. figure:: ../graphs/global.png
+.. figure:: ../graphs/global.svg
 
     Global model graph
 
 
-API
----
-
 .. toctree::
+    :hidden:
 
     osc_server.rst
-    graphql.rst
-    api/index.rst
+    story_graph.rst
+    stream.rst
+    gencaster.rst
diff --git a/docs/back/api/story_graph.rst → docs/back/story_graph.rst b/docs/back/api/story_graph.rst → docs/back/story_graph.rst
diff --git a/docs/back/api/stream.rst → docs/back/stream.rst b/docs/back/api/stream.rst → docs/back/stream.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -88,3 +88,5 @@
 autodoc_default_options = {
     "exclude-members": "DoesNotExist,MultipleObjectsReturned",
 }
+
+graphviz_output_format = "svg"
diff --git a/docs/deployment.rst b/docs/deployment.rst
@@ -1,3 +1,5 @@
+.. _deployment:
+
 Deployment
 ==========
 
@@ -39,7 +41,7 @@ while a dev deployment can look like this
   SENTRY_DSN_CASTER_FRONT="https://changeMe.io"
 
 
-.. _services:
+.. _deployment-services:
 
 Services
 ^^^^^^^^

diff --git a/docs/editor.rst b/docs/editor.rst
@@ -9,10 +9,10 @@ Caster Editor
 
 .. seealso::
 
-    This documents covers the editing of a *story graph*.
-    For the concepts of such a graph see :ref:`Story Graph`.
+    This documents covers the editing of a :term:`Story Graph` through the editor.
+    For an introduction to the concepts of Gencaster, such as the editing and capabilities of the story graph, also take a look ot the :ref:`tutorial`.
 
-The editor is a website which allows to create and modify a :ref:`Story Graph`.
+The editor is a website which allows to create and modify a :term:`Story Graph`.
 It is possible that many users at once can collaboratively edit this story graph, and also the modifications will be applied in real time to an already running stream, which allows for live coding setups.
 
 .. figure:: ./assets/editor.png
@@ -49,6 +49,8 @@ There are multiple types of script cells for different contexts.
        e.g. PopUps on the :ref:`caster-front`.
        Anything that should be decided dynamically (e.g. day vs night) should be coded within Python.
 
+.. _editor_markdown:
+
 Markdown
 ^^^^^^^^
 
@@ -103,7 +105,7 @@ To use this ``name`` within a Markdown cell can be archived via
 
 .. code-block:: markdown
 
-    Hello ${var}`name`. I hope you are doing fine.
+    Hello {var}`name`. I hope you are doing fine.
 
 where the *${var}`name* will be replaced with the name provided through the popup, so for example *Hello Alice. I hope you are doing fine*.
 
@@ -120,6 +122,8 @@ The *volume* slider controls the volume of the audio on the stream.
 
 The *edit* button allows to change the associated audio file by uploading a new file or search through existing files.
 
+.. _editor_python:
+
 Python
 ^^^^^^
 

diff --git a/docs/front.rst b/docs/front.rst
diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -0,0 +1,145 @@
+Glossary
+========
+
+.. glossary::
+
+    Backend
+
+        See :term:`Services`.
+
+    Django
+
+        `Django <https://www.djangoproject.com/>`_ is used as the web server framework for Gencaster.
+        For example, it manages the database and wraps the :term:`Engine` into a :term:`GraphQL` connection.
+
+    Docker
+
+        Docker is a virtualization software which allows to specify the runtime of a service through code.
+        This helps to make the installation, deployment and management of Gencaster easier.
+
+    Edge
+    Connection
+
+        Connects an entry :term:`node door<Node door>` with an exit node door.
+
+        See :class:`story_graph.models.Edge`.
+
+    Editor
+
+        See :term:`Services`.
+
+    Engine
+
+        The story graph engine traverses the :term:`Story Graph` and manages any script cell executions and allocations.
+
+        See :class:`story_graph.engine.Engine`.
+
+    Frontend
+
+        See :term:`Services`.
+
+    Graph
+    Story Graph
+
+        A graph is a key component of Gencaster and is used to define the score of a story within Gencaster.
+        A graph stores the content, metadata and code statements which will control and influence the stream of the listener.
+        Each Graph consists of multiple :term:`nodes <Node>` which are connected through :term:`edges<Edge>`.
+
+        See :class:`story_graph.models.Graph`.
+
+    GraphQL
+
+        GraphQL has nothing to do with :term:`Story Graph`, but instead is a communication protocol used between :term:`Frontend` and :term:`Backend`.
+
+        See :ref:`schema`.
+
+    Janus
+
+        The WebRTC server used to distribute/broadcast the sonic output of :term:`scsynth` via :term:`WebRTC`.
+
+    Node
+
+        A node is an entity within the :term:`Story Graph` and consists of any number of :term:`script cells<Script Cell>` as well as any number of :term:`node doors<Node door>`.
+
+        See :class:`story_graph.models.Node`.
+
+    Node door
+
+        The entering and exiting of a :term:`node <Node>` is managed through *node doors*.
+        Each node has at least an default exit door, but can also have multiple exit nodes.
+        Additionally, each node also has an entry door which enforces the flow such that an *exit* door can be only connected to an *input* door of a node.
+
+        Also see :ref:`the node door tutorial<tutorial_node_door>` for further information.
+
+        See :class:`story_graph.models.NodeDoor`.
+
+    Pipewire
+
+        Used as a replacement for Jack within Gencaster, which manages the *piping* of the :term:`scsynth` output to :term:`Janus`.
+        Gencaster used to rely on Jack but the virtualization performance was very bad, which Pipewire fixed.
+
+    Services
+
+        See :ref:`services`.
+
+    Script cell
+
+        A script cell wrap code statements, see :ref:`tutorial_script_cell`.
+
+        See :class:`story_graph.models.ScriptCell`.
+
+    sclang
+
+        *sclang* is the programming language of the SuperCollider framework.
+        Within Gencaster it is used to control the content of the stream.
+
+    scsynth
+
+        scsyth is the synthesis enginge of SuperCollider and is responsible to generate sounds on the Gencaster stream.
+
+    Stream
+
+        A stream combines a listener with a :term:`Stream Point` and a :term:`Story Graph`.
+        There can be multiple listeners on a stream, determined by the :term:`Stream Assignment Policy`.
+        If the listener count becomes 0, the stream will be closed and the stream point will be available for the next listener.
+
+        See :class:`stream.models.Stream`.
+
+    Stream Assignment Policy
+
+        See :class:`story_graph.models.Graph.StreamAssignmentPolicy`.
+
+    Stream Point
+    Streaming Point
+
+
+        A stream point encapsules a combination of a :term:`Janus` `stream <https://janus.conf.meetecho.com/docs/streaming.html>`_, optional `audio bridge <https://janus.conf.meetecho.com/docs/audiobridge.html>`_ and a :term:`scsynth` instance.
+        Gencaster can only manage as many parallel streams as there are stream points available.
+
+        See :class:`stream.models.StreamPoint`.
+
+    Stream Variable
+
+        Stream variable allow to attach information on a :term:`stream<Stream>`.
+
+        See :class:`stream.models.StreamVariable`.
+
+        .. important::
+
+            A stream variable is **always** a string.
+            Even if a stream variable has been set to a number or boolean value through a Python cell, the stream variable will be a string in the next script cell.
+
+    SuperCollider
+
+        SuperCollider is a framework for algorithmic composition and beyond.
+        Gencaster uses :term:`scsynth` and :term:`sclang` in order to create sounds on the stream.
+
+    Vue
+
+        `Vue <https://vuejs.org/>`_ is a JavaScript framework which is used to build to :term:`Frontend` and the :term:`Editor`.
+
+    WebRTC
+
+        WebRTC is the streaming technology which is used by Gencaster.
+        It is supported by all major browsers and allows to distribute media in real time and in high quality.
+        The actually used WebRTC server is `Janus <https://janus.conf.meetecho.com/>`_.
-Original file line number
+Diff line change
@@ -1,4 +1,6 @@
     """
+    .. _schema:
     Schema
     ======
@@ Expand Down @@