documentation updates

Author: rmorshea

docs/examples.py

@@ -23,7 +23,7 @@ def load_examples() -> Iterator[tuple[str, Callable[[], ComponentType]]]:
 def all_example_names() -> set[str]:
     names = set()
     for file in _iter_example_files(SOURCE_DIR):
-        path = file.parent if file.name == "app.py" else file
+        path = file.parent if file.name == "main.py" else file
         names.add("/".join(path.relative_to(SOURCE_DIR).with_suffix("").parts))
     return names
 
@@ -48,7 +48,7 @@ def get_main_example_file_by_name(
 ) -> Path:
     path = _get_root_example_path_by_name(name, relative_to)
     if path.is_dir():
-        return path / "app.py"
+        return path / "main.py"
     else:
         return path.with_suffix(".py")
 

docs/source/_exts/idom_example.py

@@ -51,7 +51,7 @@ def run(self):
         if len(ex_files) == 1:
             labeled_tab_items.append(
                 (
-                    "app.py",
+                    "main.py",
                     _literal_include(
                         path=ex_files[0],
                         linenos=show_linenos,

docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/adding_state_variable/main.py

@@ -151,7 +151,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Initial render</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 2
 
@@ -165,7 +165,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Initial state declaration</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 3
 
@@ -181,7 +181,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Define event handler</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 5
 
@@ -196,7 +196,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Return the view</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 16
 
@@ -212,7 +212,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>User interaction</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 5
 
@@ -226,7 +226,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>New state is set</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 6
 
@@ -242,7 +242,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Next render begins</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 2
 
@@ -256,7 +256,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Next state is acquired</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
             :emphasize-lines: 3
 
@@ -272,7 +272,7 @@ below highlights a line of code where something of interest occurs:
 
             <h2>Repeat...</h2>
 
-        .. literalinclude:: _examples/adding_state_variable/app.py
+        .. literalinclude:: _examples/adding_state_variable/main.py
             :lines: 12-33
 
         From this point on, the steps remain the same. The only difference being the

docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/isolated_state/main.py

@@ -3,7 +3,7 @@
 
 @component
 def App():
-    return html.h1("Hello, World!")
+    return html.h1("Hello, world!")
 
 
 run(App)

docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/multiple_state_variables/main.py

@@ -0,0 +1,23 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import fastapi as fastapi_server
+
+
+# the run() function is the entry point for examples
+fastapi_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from fastapi import FastAPI
+
+from idom import component, html
+from idom.server.fastapi import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = FastAPI()
+configure(app, HelloWorld)

docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/app.py renamed to docs/source/guides/adding-interactivity/components-with-state/_examples/when_variables_are_not_enough/main.py

@@ -0,0 +1,23 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import flask as flask_server
+
+
+# the run() function is the entry point for examples
+flask_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from flask import Flask
+
+from idom import component, html
+from idom.server.flask import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = Flask(__name__)
+configure(app, HelloWorld)

docs/source/guides/adding-interactivity/components-with-state/index.rst

@@ -0,0 +1,27 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import sanic as sanic_server
+
+
+# the run() function is the entry point for examples
+sanic_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from sanic import Sanic
+
+from idom import component, html
+from idom.server.sanic import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = Sanic("MyApp")
+configure(app, HelloWorld)
+
+
+if __name__ == "__main__":
+    app.run(port=8000)

docs/source/guides/escape-hatches/_examples/super_simple_chart/app.py renamed to docs/source/guides/escape-hatches/_examples/super_simple_chart/main.py

@@ -0,0 +1,23 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import starlette as starlette_server
+
+
+# the run() function is the entry point for examples
+starlette_server.configure = lambda _, cmpt: run(cmpt)
+
+
+from starlette.applications import Starlette
+
+from idom import component, html
+from idom.server.starlette import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+app = Starlette()
+configure(app, HelloWorld)

docs/source/guides/getting-started/_examples/hello_world.py

@@ -0,0 +1,32 @@
+# :lines: 11-
+
+from idom import run
+from idom.server import tornado as tornado_server
+
+
+# the run() function is the entry point for examples
+tornado_server.configure = lambda _, cmpt: run(cmpt)
+
+
+import tornado.ioloop
+import tornado.web
+
+from idom import component, html
+from idom.server.tornado import configure
+
+
+@component
+def HelloWorld():
+    return html.h1("Hello, world!")
+
+
+def make_app():
+    app = tornado.web.Application()
+    configure(app, HelloWorld)
+    return app
+
+
+if __name__ == "__main__":
+    app = make_app()
+    app.listen(8000)
+    tornado.ioloop.IOLoop.current().start()

docs/source/guides/getting-started/_examples/run_fastapi.py

@@ -1,4 +1,4 @@
 import idom
 
 
-idom.run(idom.sample.App)
+idom.run(idom.sample.SampleApp)

docs/source/guides/getting-started/_examples/run_flask.py

@@ -2,10 +2,10 @@
 from sanic.response import file
 
 from idom import component, html
-from idom.server.sanic import Config, PerClientStateServer
+from idom.server.sanic import Options, configure
 
 
-app = Sanic(__name__)
+app = Sanic("MyApp")
 
 
 @app.route("/")
@@ -18,6 +18,6 @@ def IdomView():
     return html.code("This text came from an IDOM App")
 
 
-PerClientStateServer(IdomView, app=app, config=Config(url_prefix="/_idom"))
+configure(app, IdomView, Options(url_prefix="/_idom"))
 
 app.run(host="127.0.0.1", port=5000)

docs/source/guides/getting-started/_examples/run_sanic.py

@@ -46,19 +46,35 @@ notebook linked below will demonstrate how to do this:
 Section 1: Installing IDOM
 --------------------------
 
-The next fastest option is to install IDOM with ``pip``:
+The next fastest option is to install IDOM along with a supported server (like
+``starlette``) with ``pip``:
 
 .. code-block:: bash
 
-    pip install "idom[stable]"
+    pip install "idom[starlette]"
 
 To check that everything is working you can run the sample application:
 
 .. code-block:: bash
 
-    python -c "import idom; idom.run(idom.sample.App, open_browser=True)"
+    python -c "import idom; idom.run(idom.sample.SampleApp)"
 
-This should automatically open up a browser window to a page that looks like this:
+.. note::
+
+    This launches a simple development server which is good enough for testing, but
+    probably not what you want to use in production. When deploying in production,
+    there's a number of different ways of :ref:`running IDOM <Section 2: Running IDOM>`.
+
+You should then see a few log messages:
+
+.. code-block:: text
+
+    2022-03-27T11:58:59-0700 | WARNING | You are running a development server. Change this before deploying in production!
+    2022-03-27T11:58:59-0700 | INFO | Running with 'Starlette' at http://127.0.0.1:8000
+
+The second log message includes a URL indicating where you should go to view the app.
+That will usually be http://127.0.0.1:8000. Once you go to that URL you should see
+something like this:
 
 .. card::
 
@@ -70,9 +86,8 @@ If you get a ``RuntimeError`` similar to the following:
 
     Found none of the following builtin server implementations...
 
-Then be sure you installed ``"idom[stable]"`` and not just ``idom``.
-
-For anything else, report your issue in IDOM's :discussion-type:`discussion forum
+Then be sure you run ``pip install "idom[starlette]"`` instead of just ``idom``. For
+anything else, report your issue in IDOM's :discussion-type:`discussion forum
 <problem>`.
 
 .. card::

docs/source/guides/getting-started/_examples/run_starlette.py

@@ -1,34 +1,42 @@
 Installing IDOM
 ===============
 
-The easiest way to ``pip`` install idom is to do so using the ``stable`` option:
+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:
 
 .. code-block:: bash
 
-    pip install "idom[stable]"
+    pip install "idom[starlette]"
 
-This includes a set of default dependencies for one of the builtin web server
-implementation. If you want to install IDOM without these dependencies you may simply
-``pip install idom``.
+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:
+
+.. code-block:: bash
+
+    pip install idom
 
 
-Installing Other Servers
-------------------------
+Officially Supported Servers
+----------------------------
 
 IDOM includes built-in support for a variety web server implementations. To install the
-required dependencies for each you should substitute ``stable`` from the ``pip install``
-command above with one of the options below:
+required dependencies for each you should substitute ``starlette`` from the ``pip
+install`` command above with one of the options below:
 
 - ``fastapi`` - https://fastapi.tiangolo.com
 - ``flask`` - https://palletsprojects.com/p/flask/
 - ``sanic`` - https://sanicframework.org
+- ``starlette`` - https://www.starlette.io/
 - ``tornado`` - https://www.tornadoweb.org/en/stable/
 
 If you need to, you can install more than one option by separating them with commas:
 
 .. code-block:: bash
 
-    pip install idom[fastapi,flask,sanic,tornado]
+    pip install "idom[fastapi,flask,sanic,starlette,tornado]"
 
 Once this is complete you should be able to :ref:`run IDOM <Running IDOM>` with your
 :ref:`chosen server implementation <choosing a server implementation>`.
@@ -40,7 +48,7 @@ Installing In Other Frameworks
 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
-run IDOM in the supported frameworks, follow the links below:
+run IDOM in these supported frameworks, follow the links below:
 
 .. raw:: html