rework docs to use backend instead of server

Author: rmorshea

docs/source/guides/escape-hatches/writing-your-own-backend.rst

@@ -0,0 +1,8 @@
+.. _Writing Your Own Backend:
+
+Writing Your Own Backend 🚧
+===========================
+
+.. note::
+
+    Under construction 🚧

docs/source/guides/escape-hatches/writing-your-own-server.rst

@@ -1,28 +1,28 @@
 Installing IDOM
 ===============
 
-Installing IDOM with ``pip`` will generally require doing so alongside a supported
-server implementation. This can be done by specifying an installation extra using square
-brackets. For example, if we want to run IDOM using `Starlette
-<https://www.starlette.io/>`__ we would run:
+Installing IDOM with ``pip`` will typically require doing so alongside a built-in
+backend implementation. This can be done by specifying an installation extra using
+square brackets. For example, if we want to run IDOM using the `Starlette
+<https://www.starlette.io/>`__ backend we would run:
 
 .. code-block:: bash
 
     pip install "idom[starlette]"
 
-If you want to install a "pure" version of IDOM without a server implementation you can
-do so without any installation extras. You might do this if you wanted to user a server
-which is not officially supported or if you wanted to manually pin your dependencies:
+If you want to install a "pure" version of IDOM without a backend implementation you can
+do so without any installation extras. You might do this if you wanted to use a backend
+which does not have built-in support or if you wanted to manually pin your dependencies:
 
 .. code-block:: bash
 
     pip install idom
 
 
-Officially Supported Servers
-----------------------------
+Built-in Backends
+-----------------
 
-IDOM includes built-in support for a variety web server implementations. To install the
+IDOM includes built-in support for a variety backend implementations. To install the
 required dependencies for each you should substitute ``starlette`` from the ``pip
 install`` command above with one of the options below:
 
@@ -39,15 +39,15 @@ If you need to, you can install more than one option by separating them with com
     pip install "idom[fastapi,flask,sanic,starlette,tornado]"
 
 Once this is complete you should be able to :ref:`run IDOM <Running IDOM>` with your
-chosen server implementation.
+chosen implementation.
 
 
-Installing In Other Frameworks
-------------------------------
+Using Other Backends
+--------------------
 
-While IDOM can run in a variety of contexts, sometimes web frameworks require extra work
-in order to integrate with them. In these cases, the IDOM team distributes bindings for
-various frameworks as separate Python packages. For documentation on how to install and
+While IDOM can run in a variety of contexts, sometimes frameworks require extra work in
+order to integrate with them. In these cases, the IDOM team distributes bindings for
+those frameworks as separate Python packages. For documentation on how to install and
 run IDOM in these supported frameworks, follow the links below:
 
 .. raw:: html

docs/source/guides/getting-started/installing-idom.rst

@@ -12,11 +12,11 @@ Running IDOM in Production
 --------------------------
 
 The first thing you'll need to do if you want to run IDOM in production is choose a
-server implementation and follow its documentation on how to create and run an
-application. This is the server :ref:`you probably chose <Officially Supported Servers>`
-when installing IDOM. Then you'll need to configure that application with an IDOM view.
-We should the basics how how to run each supported server below, but all implementations
-will follow a pattern similar to the following:
+backend implementation and follow its documentation on how to create and run an
+application. This is the backend :ref:`you probably chose <Officially Supported
+Backends>` when installing IDOM. Then you'll need to configure that application with an
+IDOM view. We show the basics of how to set up, and then run, each supported backend
+below, but all implementations will follow a pattern similar to the following:
 
 .. code-block::
 
@@ -34,17 +34,17 @@ will follow a pattern similar to the following:
     app = Application()
     configure(app, HelloWorld)
 
-You'll then run this ``app`` using a `ASGI <https://asgi.readthedocs.io/en/latest/>`__ or
-`WSGI <https://wsgi.readthedocs.io/>`__ server from the command line.
+You'll then run this ``app`` using an `ASGI <https://asgi.readthedocs.io/en/latest/>`__
+or `WSGI <https://wsgi.readthedocs.io/>`__ server from the command line.
 
 
 Running with `FastAPI <https://fastapi.tiangolo.com>`__
 .......................................................
 
 .. idom:: _examples/run_fastapi
 
-Then assuming you put this in ``main.py``, you can run the ``app`` using `Uvicorn
-<https://www.uvicorn.org/>`__:
+Then assuming you put this in ``main.py``, you can run the ``app`` using the `Uvicorn
+<https://www.uvicorn.org/>`__ ASGI server:
 
 .. code-block:: bash
 
@@ -56,8 +56,8 @@ Running with `Flask <https://palletsprojects.com/p/flask/>`__
 
 .. idom:: _examples/run_flask
 
-Then assuming you put this in ``main.py``, you can run the ``app`` using `Gunicorn
-<https://gunicorn.org/>`__:
+Then assuming you put this in ``main.py``, you can run the ``app`` using the `Gunicorn
+<https://gunicorn.org/>`__ WSGI server:
 
 .. code-block:: bash
 
@@ -82,8 +82,8 @@ Running with `Starlette <https://www.starlette.io/>`__
 
 .. idom:: _examples/run_starlette
 
-Then assuming you put this in ``main.py``, you can run the application using `Uvicorn
-<https://www.uvicorn.org/>`__:
+Then assuming you put this in ``main.py``, you can run the application using the
+`Uvicorn <https://www.uvicorn.org/>`__ ASGI server:
 
 .. code-block:: bash
 
@@ -143,10 +143,10 @@ Errors will be displayed where the uppermost component is located in the view:
 .. idom:: _examples/debug_error_example
 
 
-Server Configuration Options
-----------------------------
+Backend Configuration Options
+-----------------------------
 
-IDOM's various server implementations come with ``Options`` that can be passed to their
+IDOM's various backend implementations come with ``Options`` that can be passed to their
 respective ``configure()`` functions in the following way:
 
 .. code-block::
@@ -187,8 +187,8 @@ embedding one the examples from this documentation into your own webpage:
 .. note::
 
     For more information on how to use the client see the :ref:`Javascript API`
-    reference. Or if you need to, your can :ref:`write your own server implementation
-    <writing your own server>`.
+    reference. Or if you need to, your can :ref:`write your own backend implementation
+    <writing your own backend>`.
 
 As mentioned though, this is connecting to the server that is hosting this
 documentation. If you want to connect to a view from your own server, you'll need to

docs/source/guides/getting-started/running-idom.rst

@@ -73,9 +73,14 @@ of HTML element called an ``h1`` `section heading
 <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements>`__.
 Importantly though, a ``@component`` decorator has been applied to the ``App`` function
 to turn it into a :ref:`component <Your First Components>`. Finally, we :ref:`run
-<Running IDOM>` an application server by passing the ``App`` component to the ``run()``
+<Running IDOM>` a development server by passing the ``App`` component to the ``run()``
 function.
 
+.. note::
+
+    See :ref:`Running IDOM in Production` to learn how to use a production-grade server
+    to run IDOM.
+
 
 Learning IDOM
 -------------

docs/source/index.rst

@@ -5,7 +5,7 @@
 
 from idom.types import RootComponentConstructor
 
-from .types import Location, ServerImplementation
+from .types import BackendImplementation, Location
 from .utils import all_implementations
 
 
@@ -45,10 +45,10 @@ def use_location() -> Location:
     return _default_implementation().use_location()
 
 
-_DEFAULT_IMPLEMENTATION: ServerImplementation[Any] | None = None
+_DEFAULT_IMPLEMENTATION: BackendImplementation[Any] | None = None
 
 
-def _default_implementation() -> ServerImplementation[Any]:
+def _default_implementation() -> BackendImplementation[Any]:
     """Get the first available server implementation"""
     global _DEFAULT_IMPLEMENTATION
 

src/idom/backend/default.py

@@ -13,7 +13,7 @@
 
 
 @runtime_checkable
-class ServerImplementation(Protocol[_App]):
+class BackendImplementation(Protocol[_App]):
     """Common interface for IDOM's builti-in server implementations"""
 
     def configure(

src/idom/backend/types.py

@@ -13,7 +13,7 @@
 from idom.config import IDOM_WEB_MODULES_DIR
 from idom.types import RootComponentConstructor
 
-from .types import ServerImplementation
+from .types import BackendImplementation
 
 
 logger = logging.getLogger(__name__)
@@ -32,7 +32,7 @@ def run(
     component: RootComponentConstructor,
     host: str = "127.0.0.1",
     port: int | None = None,
-    implementation: ServerImplementation[Any] | None = None,
+    implementation: BackendImplementation[Any] | None = None,
 ) -> None:
     """Run a component with a development server"""
     logger.warn(
@@ -113,15 +113,15 @@ def find_available_port(
     )
 
 
-def all_implementations() -> Iterator[ServerImplementation[Any]]:
+def all_implementations() -> Iterator[BackendImplementation[Any]]:
     """Yield all available server implementations"""
     for name in SUPPORTED_PACKAGES:
         try:
             module = import_module(f"idom.server.{name}")
         except ImportError:  # pragma: no cover
             continue
 
-        if not isinstance(module, ServerImplementation):
+        if not isinstance(module, BackendImplementation):
             raise TypeError(  # pragma: no cover
                 f"{module.__name__!r} is an invalid implementation"
             )

src/idom/backend/utils.py

@@ -8,7 +8,7 @@
 from urllib.parse import urlencode, urlunparse
 
 from idom.backend import default as default_server
-from idom.backend.types import ServerImplementation
+from idom.backend.types import BackendImplementation
 from idom.backend.utils import find_available_port
 from idom.widgets import hotswap
 
@@ -36,7 +36,7 @@ def __init__(
         host: str = "127.0.0.1",
         port: Optional[int] = None,
         app: Any | None = None,
-        implementation: ServerImplementation[Any] | None = None,
+        implementation: BackendImplementation[Any] | None = None,
         options: Any | None = None,
     ) -> None:
         self.host = host

src/idom/testing/server.py

@@ -4,7 +4,7 @@
 - :mod:`idom.server.types`
 """
 
-from .backend.types import Location, ServerImplementation
+from .backend.types import BackendImplementation, Location
 from .core.hooks import Context
 from .core.types import (
     ComponentConstructor,
@@ -45,5 +45,5 @@
     "VdomChildren",
     "VdomDict",
     "VdomJson",
-    "ServerImplementation",
+    "BackendImplementation",
 ]