Harden docs against FailWarning (#376)

* Cleanup FailWarnings in the docs

* Fail docs build if FailWarning found

.github/workflows/test.yml

@@ -54,6 +54,9 @@ jobs:
       run: pip install -e .[docs]
     - name: Build docs
       run: make docs
+    - name: Check for FailWarning
+      run: "! grep -R ': FailWarning: ' *"
+      working-directory: docs/build/html
 
   lint:
     name: Lint Supriya

README.md

@@ -91,6 +91,11 @@ Allocate it on the server:
 
     >>> _ = server.add_synthdefs(simple_sine)
 
+... and then sync the server before proceeding to ensure the SynthDef has been
+fully parsed by scsynth:
+
+    >>> _ = server.sync()
+
 ### 5. Create some nodes
 
 Create and allocate a group:

docs/source/index.rst

@@ -96,6 +96,11 @@ Allocate it on the server::
 
     >>> _ = server.add_synthdefs(simple_sine)
 
+... and then sync the server before proceeding to ensure the SynthDef has been
+fully parsed by scsynth::
+
+    >>> _ = server.sync()
+
 5. Create some nodes
 ````````````````````
 

docs/source/nodes.rst

@@ -177,12 +177,18 @@ wet audio mixed with the dry::
 Create a synth using the "ticker" SynthDef, replacing the "default" synth we
 just created::
 
-    >>> synth.add_synth(ticker_synthdef, frequency=4, add_action="replace")
+    >>> with server.at():
+    ...     with server.add_synthdefs(ticker_synthdef):
+    ...         synth.add_synth(ticker_synthdef, frequency=4, add_action="replace")
+    ...
 
 Then create a second synth using the "reverb" SynthDef, positioning it after
 the previous synth with an ``ADD_TO_TAIL`` :term:`add action`::
 
-    >>> server.add_synth(reverb_synthdef, add_action="add_to_tail")
+    >>> with server.at():
+    ...     with server.add_synthdefs(reverb_synthdef):
+    ...         server.add_synth(reverb_synthdef, add_action="add_to_tail")
+    ... 
 
 Note the order of the two synths (you can tell by their SynthDef names), and
 how the reverberation kicks in when you instantiate the second synth::
@@ -203,11 +209,19 @@ Deleting
 Reset the server for a clean slate, then add a synth::
 
     >>> server.reset()
+
+::
+
     >>> with server.at():
     ...     with server.add_synthdefs(supriya.default):
     ...         synth = server.add_synth(supriya.default)
     ...
 
+.. book::
+    :hide:
+
+    >>> server.sync()  # wait for synthdefs to load
+
 You can remove a node from the server by :term:`freeing <free>` it::
 
     >>> synth.free()
@@ -226,11 +240,6 @@ from the server. By convention with :term:`sclang`, synths with a ``gate``
 control can be released, although it's up to the author of the :term:`SynthDef`
 to guarantee they behave as expected.
 
-.. book::
-    :hide:
-
-    >>> synth.free()
-
 Groups can also be freed::
 
     >>> group = server.add_group()
@@ -253,6 +262,11 @@ Reset the server for a clean slate::
     ...         synth_c = group.add_synth(supriya.default, frequency=555)
     ...
 
+.. book::
+    :hide:
+
+    >>> server.sync()  # wait for synthdefs to load
+
 Every node has a ``id_`` and a reference to its context::
 
     >>> group.id_, group.context
@@ -312,13 +326,18 @@ Reset the server for a clean slate::
 ... then add a group, a *ticker* synth and a *reverb* synth using the two
 :term:`SynthDefs <SynthDef>` we defined earlier::
 
-    >>> group = server.add_group()
     >>> with server.at():
+    ...     group = server.add_group()
     ...     with server.add_synthdefs(ticker_synthdef, reverb_synthdef):
     ...         ticker_synth = group.add_synth(ticker_synthdef)
     ...         reverb_synth = group.add_synth(reverb_synthdef, add_action="add_to_tail")
     ...
 
+.. book::
+    :hide:
+
+    >>> server.sync()  # wait for synthdefs to load
+
 Note the click train emitted by the *ticker* synth and the reverberation added
 by the *reverb* synth. 
 
@@ -334,13 +353,13 @@ Move the *reverb* synth to the :term:`head` of its parent group - *before* the
 *ticker* synth - and notice how the click train's reverberation dies out::
 
     >>> reverb_synth.move(group, "add_to_head")
-    >>> print(group)
+    >>> print(server.query_tree())
 
 Now move the *reverb* synth *after* the *ticker* synth, and listen to the
 reverberation return::
 
     >>> reverb_synth.move(ticker_synth, "add_after")
-    >>> print(group)
+    >>> print(server.query_tree())
 
 Setting controls
 ````````````````

docs/source/servers.rst

@@ -170,10 +170,13 @@ Inspect the "status" of audio processing::
 
     Server status is a great way of tracking :term:`scsynth`'s CPU usage.
 
-Let's add a synth - explained :doc:`soon <nodes>` - to increase the
+Let's add a SynthDef and a synth - explained :doc:`soon <nodes>` - to increase the
 complexity of the status output::
 
-    >>> synth = server.add_synth(supriya.default)
+    >>> with server.at():
+    ...     with server.add_synthdefs(supriya.default):
+    ...         synth = server.add_synth(supriya.default)
+    ...
 
 .. book::
     :hide:
@@ -219,6 +222,8 @@ Interaction
     :hide:
 
     >>> server.boot()
+    >>> server.add_synthdefs(supriya.default)
+    >>> server.sync()
 
 The server provides a variety of methods for interacting with it and modifying
 its state.

supriya/contexts/realtime.py

@@ -779,8 +779,8 @@ def reset(self) -> "Server":
         """
         with self.at():
             self.clear_schedule()
-            self.free_all_synthdefs()
             self.free_group_children(self.root_node)
+            self.free_all_synthdefs()
         self.sync()
         self._teardown_state()
         self._setup_allocators()