API docs + some fine tuning for Plugin API

docs/api/trinity/api.cli.rst

@@ -0,0 +1,46 @@
+Command Line Interface (CLI)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: shell
+
+    usage: trinity [-h] [--version] [--trinity-root-dir TRINITY_ROOT_DIR]
+                [-l {debug,info}] [--network-id NETWORK_ID | --ropsten]
+                [--sync-mode {full,light} | --light] [--data-dir DATA_DIR]
+                [--nodekey NODEKEY] [--nodekey-path NODEKEY_PATH]
+                {console,attach} ...
+
+    positional arguments:
+    {console,attach}
+        console             run the chain and start the trinity REPL
+        attach              open an REPL attached to a currently running chain
+
+    optional arguments:
+    -h, --help            show this help message and exit
+
+    sync mode:
+    --version             show program's version number and exit
+    --trinity-root-dir TRINITY_ROOT_DIR
+                            The filesystem path to the base directory that trinity
+                            will store it's information. Default:
+                            $XDG_DATA_HOME/.local/share/trinity
+
+    logging:
+    -l {debug,info}, --log-level {debug,info}
+                            Sets the logging level
+
+    network:
+    --network-id NETWORK_ID
+                            Network identifier (1=Mainnet, 3=Ropsten)
+    --ropsten             Ropsten network: pre configured proof-of-work test
+                            network. Shortcut for `--networkid=3`
+
+    sync mode:
+    --sync-mode {full,light}
+    --light               Shortcut for `--sync-mode=light`
+
+    chain:
+    --data-dir DATA_DIR   The directory where chain data is stored
+    --nodekey NODEKEY     Hexadecimal encoded private key to use for the nodekey
+    --nodekey-path NODEKEY_PATH
+                            The filesystem path to the file which contains the
+                            nodekey

docs/api/trinity/extensibility/api.extensibility.events.rst

@@ -0,0 +1,8 @@
+Events
+======
+
+.. autoclass:: trinity.extensibility.events.PluginStartedEvent
+  :members:
+
+.. autoclass:: trinity.extensibility.events.ResourceAvailableEvent
+  :members:

docs/api/trinity/extensibility/api.extensibility.exceptions.rst

@@ -0,0 +1,9 @@
+Exceptions
+==========
+
+.. autoclass:: trinity.extensibility.exceptions.EventBusNotReady
+  :members:
+
+.. autoclass:: trinity.extensibility.exceptions.UnsuitableShutdownError
+  :members:
+

docs/api/trinity/extensibility/api.extensibility.plugin.rst

@@ -0,0 +1,39 @@
+Plugin
+======
+
+
+PluginContext
+-------------
+
+.. autoclass:: trinity.extensibility.plugin.PluginContext
+  :members:
+
+BasePlugin
+----------
+
+.. autoclass:: trinity.extensibility.plugin.BasePlugin
+  :members:
+
+BaseSyncStopPlugin
+------------------
+
+.. autoclass:: trinity.extensibility.plugin.BaseSyncStopPlugin
+  :members:
+
+BaseAsyncStopPlugin
+-------------------
+
+.. autoclass:: trinity.extensibility.plugin.BaseAsyncStopPlugin
+  :members:
+
+BaseMainProcessPlugin
+---------------------
+
+.. autoclass:: trinity.extensibility.plugin.BaseMainProcessPlugin
+  :members:
+
+BaseIsolatedPlugin
+------------------
+
+.. autoclass:: trinity.extensibility.plugin.BaseIsolatedPlugin
+  :members:

docs/api/trinity/extensibility/api.extensibility.plugin_manager.rst

@@ -0,0 +1,27 @@
+PluginManager
+=============
+
+BaseManagerProcessScope
+-----------------------
+
+.. autoclass:: trinity.extensibility.plugin_manager.BaseManagerProcessScope
+  :members:
+
+MainAndIsolatedProcessScope
+---------------------------
+
+.. autoclass:: trinity.extensibility.plugin_manager.MainAndIsolatedProcessScope
+  :members:
+
+SharedProcessScope
+------------------
+
+.. autoclass:: trinity.extensibility.plugin_manager.SharedProcessScope
+  :members:
+
+PluginManager
+-------------
+
+.. autoclass:: trinity.extensibility.plugin_manager.PluginManager
+  :members:
+

docs/api/trinity/extensibility/index.rst

@@ -0,0 +1,16 @@
+Extensibility
+=============
+
+.. warning::
+
+  The extensibility API isn't stable yet. Expect breaking changes.
+
+.. toctree::
+   :maxdepth: 4
+   :name: toc-eth-api-extensibility
+
+   api.extensibility.events.rst
+   api.extensibility.exceptions.rst
+   api.extensibility.plugin.rst
+   api.extensibility.plugin_manager.rst
+

docs/api/trinity/index.rst

@@ -3,49 +3,12 @@ Trinity
 
 This section aims to provide a detailed description of all APIs. If you are looking for something more hands-on or higher-level check out the existing :doc:`Trinity guides </guides/trinity/index>`.
 
-Command Line Interface (CLI)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. toctree::
+   :maxdepth: 4
+   :name: toc-api-trinity
+   :caption: API
 
-.. code-block:: shell
+   api.cli
+   extensibility/index
 
-    usage: trinity [-h] [--version] [--trinity-root-dir TRINITY_ROOT_DIR]
-                [-l {debug,info}] [--network-id NETWORK_ID | --ropsten]
-                [--sync-mode {full,light} | --light] [--data-dir DATA_DIR]
-                [--nodekey NODEKEY] [--nodekey-path NODEKEY_PATH]
-                {console,attach} ...
 
-    positional arguments:
-    {console,attach}
-        console             run the chain and start the trinity REPL
-        attach              open an REPL attached to a currently running chain
-
-    optional arguments:
-    -h, --help            show this help message and exit
-
-    sync mode:
-    --version             show program's version number and exit
-    --trinity-root-dir TRINITY_ROOT_DIR
-                            The filesystem path to the base directory that trinity
-                            will store it's information. Default:
-                            $XDG_DATA_HOME/.local/share/trinity
-
-    logging:
-    -l {debug,info}, --log-level {debug,info}
-                            Sets the logging level
-
-    network:
-    --network-id NETWORK_ID
-                            Network identifier (1=Mainnet, 3=Ropsten)
-    --ropsten             Ropsten network: pre configured proof-of-work test
-                            network. Shortcut for `--networkid=3`
-
-    sync mode:
-    --sync-mode {full,light}
-    --light               Shortcut for `--sync-mode=light`
-
-    chain:
-    --data-dir DATA_DIR   The directory where chain data is stored
-    --nodekey NODEKEY     Hexadecimal encoded private key to use for the nodekey
-    --nodekey-path NODEKEY_PATH
-                            The filesystem path to the file which contains the
-                            nodekey

trinity/extensibility/__init__.py

@@ -9,6 +9,7 @@
     BaseSyncStopPlugin,
     DebugPlugin,
     PluginContext,
+    TrinityBootInfo,
 )
 from trinity.extensibility.plugin_manager import (  # noqa: F401
     BaseManagerProcessScope,

trinity/extensibility/exceptions.py

@@ -3,18 +3,21 @@
 )
 
 
-class UnsuitableShutdownError(BaseTrinityError):
+class EventBusNotReady(BaseTrinityError):
     """
-    Raised when `shutdown` was called on a ``PluginManager`` instance that operates
-    in the ``MainAndIsolatedProcessScope`` or when ``shutdown_blocking`` was called on a
-    ``PluginManager`` instance that operates in the ``SharedProcessScope``.
+    Raised when a plugin tried to access an :class:`~lahja.eventbus.EventBus` before the plugin
+    had received its :meth:`~trinity.extensibility.plugin.BasePlugin.ready` call.
     """
     pass
 
 
-class EventBusNotReady(BaseTrinityError):
+class UnsuitableShutdownError(BaseTrinityError):
     """
-    Raised when a plugin tried to access an EventBus before the plugin
-    had received its ``ready`` call.
+    Raised when :meth:`~trinity.extensibility.plugin_manager.PluginManager.shutdown` was called on
+    a :class:`~trinity.extensibility.plugin_manager.PluginManager` instance that operates in the
+    :class:`~trinity.extensibility.plugin_manager.MainAndIsolatedProcessScope` or when
+    :meth:`~trinity.extensibility.plugin.PluginManager.shutdown_blocking` was called on a
+    :class:`~trinity.extensibility.plugin_manager.PluginManager` instance that operates in the
+    :class:`~trinity.extensibility.plugin_manager.SharedProcessScope`.
     """
     pass