Merge pull request #974 from jamesbraza/engine-docs-clarity

Clarifications to SimpleEngine in docs

docs/engine.rst

@@ -19,6 +19,7 @@ The preferred way to use the API is with an
 The examples also show a synchronous wrapper
 :class:`~chess.engine.SimpleEngine` that automatically spawns an event loop
 in the background.
+:class:`~chess.engine.SimpleEngine` methods block until there is a result.
 
 Playing
 -------
@@ -27,6 +28,8 @@ Example: Let Stockfish play against itself, 100 milliseconds per move.
 
 .. code:: python
 
+    """Using synchronous engine.SimpleEngine."""
+
     import chess
     import chess.engine
 
@@ -41,6 +44,8 @@ Example: Let Stockfish play against itself, 100 milliseconds per move.
 
 .. code:: python
 
+    """Using async engine."""
+
     import asyncio
     import chess
     import chess.engine
@@ -74,6 +79,8 @@ Example:
 
 .. code:: python
 
+    """Using synchronous engine.SimpleEngine."""
+
     import chess
     import chess.engine
 
@@ -93,6 +100,8 @@ Example:
 
 .. code:: python
 
+    """Using async engine."""
+
     import asyncio
     import chess
     import chess.engine
@@ -139,6 +148,8 @@ Example: Stream information from the engine and stop on an arbitrary condition.
 
 .. code:: python
 
+    """Using synchronous engine.SimpleEngine."""
+
     import chess
     import chess.engine
 
@@ -156,6 +167,8 @@ Example: Stream information from the engine and stop on an arbitrary condition.
 
 .. code:: python
 
+    """Using async engine."""
+
     import asyncio
     import chess
     import chess.engine
@@ -193,21 +206,27 @@ Options
 :func:`~chess.Protocol.analyse()` and
 :func:`~chess.Protocol.analysis()` accept a dictionary of options.
 
->>> import chess.engine
->>>
->>> engine = chess.engine.SimpleEngine.popen_uci("/usr/bin/stockfish")
->>>
->>> # Check available options.
->>> engine.options["Hash"]
-Option(name='Hash', type='spin', default=16, min=1, max=131072, var=[])
->>>
->>> # Set an option.
->>> engine.configure({"Hash": 32})
->>>
->>> # [...]
+.. code:: python
+
+    """Using synchronous engine.SimpleEngine."""
+
+    import chess.engine
+
+    engine = chess.engine.SimpleEngine.popen_uci("/usr/bin/stockfish")
+
+    # Check available options.
+    engine.options["Hash"]
+    # Option(name='Hash', type='spin', default=16, min=1, max=131072, var=[])
+
+    # Set an option.
+    engine.configure({"Hash": 32})
+
+    # [...]
 
 .. code:: python
 
+    """Using async engine."""
+
     import asyncio
     import chess.engine