Improve the docs of connect and serve (#1450)

* Improve the docs of `connect` and `serve`

* Fix doctest

clippy.toml

@@ -53,4 +53,5 @@ doc-valid-idents = [
   "sRGB",
   "sRGBA",
   "WebGL",
+  "WebSockets",
 ]

crates/re_sdk/src/session.rs

@@ -174,12 +174,23 @@ impl Session {
         self.recording_source = recording_source;
     }
 
-    /// Send log data to a remote server.
+    /// Send log data to a remote viewer/server.
+    ///
+    /// Usually this is done by running the `rerun` binary (`cargo install rerun`) without arguments,
+    /// and then connecting to it.
     ///
     /// Send all currently buffered messages.
     /// If we are already connected, we will re-connect to this new address.
     ///
+    /// This function returns immediately.
     /// Disconnect with [`Self::disconnect`].
+    ///
+    /// ## Example:
+    ///
+    /// ``` no_run
+    /// # let mut session = re_sdk::Session::new();
+    /// session.connect(re_sdk::default_server_addr());
+    /// ```
     pub fn connect(&mut self, addr: SocketAddr) {
         if !self.enabled {
             re_log::debug!("Rerun disabled - call to connect() ignored");
@@ -209,10 +220,16 @@ impl Session {
         }
     }
 
-    /// Serve a Rerun web viewer and stream the log messages to it.
+    /// Serve log-data over WebSockets and serve a Rerun web viewer over HTTP.
+    ///
+    /// If the `open_browser` argument is `true`, your default browser
+    /// will be opened with a connected web-viewer.
+    ///
+    /// If not, you can connect to this server using the `rerun` binary (`cargo install rerun`).
+    ///
+    /// NOTE: you can not connect one `Session` to another.
     ///
-    /// If the `open_browser` argument is set, your default browser
-    /// will be opened to show the viewer.
+    /// This function returns immediately.
     #[cfg(feature = "web_viewer")]
     pub fn serve(&mut self, open_browser: bool) {
         if !self.enabled {

crates/re_viewer/src/remote_viewer_app.rs

@@ -1,6 +1,6 @@
 use crate::App;
 
-/// Connects to a server over `WebSockets`.
+/// Connects to a server over WebSockets.
 pub struct RemoteViewerApp {
     build_info: re_build_info::BuildInfo,
     app_env: crate::AppEnvironment,

rerun_py/rerun_sdk/rerun/__init__.py

@@ -222,6 +222,8 @@ def connect(addr: Optional[str] = None) -> None:
 
     Requires that you first start a Rerun Viewer, e.g. with 'python -m rerun'
 
+    This function returns immediately.
+
     Parameters
     ----------
     addr
@@ -287,10 +289,14 @@ def spawn(port: int = 9876, connect: bool = True) -> None:
 
 def serve(open_browser: bool = True) -> None:
     """
-    Serve a Rerun Web Viewer.
+    Serve log-data over WebSockets and serve a Rerun web viewer over HTTP.
+
+    You can connect to this server using `python -m rerun`.
 
     WARNING: This is an experimental feature.
 
+    This function returns immediately.
+
     Parameters
     ----------
     open_browser