Autogenerate ServerProcess documentation instead of duplicating it

Avoid duplication in documentation

Author: manics

docs/extensions/serverprocess_documenter.py

@@ -0,0 +1,60 @@
+from autodoc_traits import ConfigurableDocumenter, TraitDocumenter
+from sphinx.application import Sphinx
+from sphinx.ext.autodoc import SUPPRESS, ClassDocumenter, ObjectMember
+from sphinx.util.typing import ExtensionMetadata
+from traitlets import Undefined
+
+
+class ServerProcessConfigurableDocumenter(ConfigurableDocumenter):
+    objtype = "serverprocessconfigurable"
+    directivetype = "class"
+    priority = 100
+
+    def get_object_members(self, want_all):
+        """
+        Only document members in this class
+        """
+        config_trait_members = self.object.class_traits(config=True).items()
+        members = [ObjectMember(name, trait) for (name, trait) in config_trait_members]
+        return False, members
+
+    def should_suppress_directive_header():
+        return True
+
+    # Skip over autodoc_traits otherwise it'll prepend c.ServerProcess
+    # to the annotation
+    def add_directive_header(self, sig):
+        print(f"{sig=}")
+        self.options.annotation = SUPPRESS
+        super(ClassDocumenter, self).add_directive_header(sig)
+
+
+class ServerProcessTraitDocumenter(TraitDocumenter):
+    objtype = "serverprocesstrait"
+    directivetype = "attribute"
+    priority = 100  # AttributeDocumenter has 10
+    member_order = 0  # AttributeDocumenter has 60
+
+    def add_directive_header(self, sig):
+        default_value = self.object.default_value
+        if default_value is Undefined:
+            default_value = ""
+        else:
+            default_value = repr(default_value)
+
+        traitlets_type = self.object.__class__.__name__
+        self.options.annotation = f"{traitlets_type}({default_value})"
+        # Skip over autodoc_traits otherwise it'll prepend c.ServerProcess
+        # to the annotation
+        super(TraitDocumenter, self).add_directive_header(sig)
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.setup_extension("autodoc_traits")
+    app.add_autodocumenter(ServerProcessConfigurableDocumenter)
+    app.add_autodocumenter(ServerProcessTraitDocumenter)
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/source/conf.py

@@ -3,6 +3,8 @@
 # Configuration reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
 #
 import datetime
+import sys
+from pathlib import Path
 
 # -- Project information -----------------------------------------------------
 # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -18,11 +20,17 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 #
+
+# Custom extensions included this repo
+extensions_dir = Path(__file__).absolute().parent.parent / "extensions"
+sys.path.append(str(extensions_dir))
+
 extensions = [
     "myst_parser",
     "sphinx_copybutton",
     "sphinxext.opengraph",
     "sphinxext.rediraffe",
+    "serverprocess_documenter",
 ]
 root_doc = "index"
 source_suffix = [".md"]

docs/source/server-process.md

@@ -15,232 +15,11 @@ as separate packages.
 Server Processes are configured with a dictionary of key value
 pairs.
 
-(server-process:cmd)=
+```{eval-rst}
 
-### `command`
-
-One of:
-
-- A list of strings that is the command used to start the
-  process. The following template strings will be replaced:
-
-  - `{port}` the port that the process should listen on. This will be 0 if it
-    should use a Unix socket instead.
-  - `{unix_socket}` the path at which the process should listen on a Unix
-    socket. This will be an empty string if it should use a TCP port.
-  - `{base_url}` the base URL of the notebook. For example, if the application
-    needs to know its full path it can be constructed from
-    `{base_url}/proxy/{port}`
-
-- A callable that takes any {ref}`callable arguments <server-process:callable-arguments>`,
-  and returns a list of strings that are used & treated same as above.
-
-If the command is not specified or is an empty list, the server process is
-assumed to be started ahead of time and already available to be proxied to.
-
-### `timeout`
-
-Timeout in seconds for the process to become ready, default `5`.
-
-A process is considered 'ready' when it can return a valid HTTP response on the
-port it is supposed to start at.
-
-### `environment`
-
-One of:
-
-- A dictionary of strings that are passed in as the environment to
-  the started process, in addition to the environment of the notebook
-  process itself. The strings `{port}`, `{unix_socket}` and
-  `{base_url}` will be replaced as for **command**.
-- A callable that takes any {ref}`callable arguments <server-process:callable-arguments>`,
-  and returns a dictionary of strings that are used & treated same as above.
-
-### `absolute_url`
-
-_True_ if the URL as seen by the proxied application should be the full URL
-sent by the user. _False_ if the URL as seen by the proxied application should
-see the URL after the parts specific to jupyter-server-proxy have been stripped.
-
-For example, with the following config:
-
-```python
-c.ServerProxy.servers = {
-    "test-server": {
-        "command": ["python3", "-m", "http.server", "{port}"],
-        "absolute_url": False
-    }
-}
+.. autoserverprocessconfigurable:: jupyter_server_proxy.config.ServerProcess
 ```
 
-When a user requests `/test-server/some-url`, the proxied server will see it
-as a request for `/some-url` - the `/test-server` part is stripped out.
-
-If `absolute_url` is set to `True` instead, the proxied server will see it
-as a request for `/test-server/some-url` instead - without any stripping.
-
-This is very useful with applications that require a `base_url` to be set.
-
-Defaults to _False_.
-
-### `port`
-
-Set the port that the service will listen on. The default is to
-automatically select an unused port.
-
-(server-process:unix-socket)=
-
-### `unix_socket`
-
-This option uses a Unix socket on a filesystem path, instead of a TCP
-port. It can be passed as a string specifying the socket path, or _True_ for
-Jupyter Server Proxy to create a temporary directory to hold the socket,
-ensuring that only the user running Jupyter can connect to it.
-
-If this is used, the `{unix_socket}` argument in the command template
-(see {ref}`server-process:cmd`) will be a filesystem path. The server should
-create a Unix socket bound to this path and listen for HTTP requests on it.
-The `port` configuration key will be ignored.
-
-```{note}
-Proxying websockets over a Unix socket requires Tornado >= 6.3.
-```
-
-### `mappath`
-
-Map request paths to proxied paths.
-Either a dictionary of request paths to proxied paths,
-or a callable that takes parameter `path` and returns the proxied path.
-
-### `launcher_entry`
-
-A dictionary with options on if / how an entry in the classic Jupyter Notebook
-'New' dropdown or the JupyterLab launcher should be added. It can contain
-the following keys:
-
-1. **enabled**
-   Set to True (default) to make an entry in the launchers. Set to False to have no
-   explicit entry.
-2. **icon_path**
-   Full path to an svg icon that could be used with a launcher. Currently only used by the
-   JupyterLab launcher, when category is "Notebook" (default) or "Console".
-3. **title**
-   Title to be used for the launcher entry. Defaults to the name of the server if missing.
-4. **path_info**
-   The trailing path that is appended to the user's server URL to access the proxied server.
-   By default it is the name of the server followed by a trailing slash.
-5. **category**
-   The category for the launcher item. Currently only used by the JupyterLab launcher.
-   By default it is "Notebook".
-
-### `new_browser_tab`
-
-_JupyterLab only_ - _True_ (default) if the proxied server URL should be opened in a new browser tab.
-_False_ if the proxied server URL should be opened in a new JupyterLab tab.
-
-If _False_, the proxied server needs to allow its pages to be rendered in an iframe. This
-is generally done by configuring the web server `X-Frame-Options` to `SAMEORIGIN`.
-For more information, refer to
-[MDN Web docs on X-Frame-Options](https://developer.mozilla.org/docs/Web/HTTP/Headers/X-Frame-Options).
-
-Note that applications might use a different terminology to refer to frame options.
-For example, RStudio uses the term _frame origin_ and require the flag
-`--www-frame-origin=same` to allow rendering of its pages in an iframe.
-
-### `request_headers_override`
-
-One of:
-
-- A dictionary of strings that are passed in as HTTP headers to the proxy
-  request. The strings `{port}`, `{unix_socket}` and `{base_url}` will be
-  replaced as for **command**.
-- A callable that takes any {ref}`callable arguments <server-process:callable-arguments>`,
-  and returns a dictionary of strings that are used & treated same as above.
-
-### `update_last_activity`
-
-Whether to report activity from the proxy to Jupyter Server. If _True_, Jupyter Server
-will be notified of new activity. This is primarily used by JupyterHub for idle detection and culling.
-
-Useful if you want to have a seperate way of determining activity through a
-proxied application.
-
-Defaults to _True_.
-
-(server-process:callable-arguments)=
-
-### `raw_socket_proxy`
-
-_True_ to proxy only websocket connections into raw stream connections.
-_False_ (default) if the proxied server speaks full HTTP.
-
-If _True_, the proxied server is treated a raw TCP (or unix socket) server that
-does not use HTTP.
-In this mode, only websockets are handled, and messages are sent to the backend
-server as raw stream data. This is similar to running a
-[websockify](https://github.com/novnc/websockify) wrapper.
-All other HTTP requests return 405.
-
-### Callable arguments
-
-Certain config options accept callables, as documented above. This should return
-the same type of object that the option normally expects.
-When you use a callable this way, it can ask for any arguments it needs
-by simply declaring it - only arguments the callable asks for will be passed to it.
-
-For example, with the following config:
-
-```python
-def _cmd_callback():
-    return ["some-command"]
-
-server_config = {
-    "command": _cmd_callback
-}
-```
-
-No arguments will be passed to `_cmd_callback`, since it doesn't ask for any. However,
-with:
-
-```python
-def _cmd_callback(port):
-    return ["some-command", "--port=" + str(port)]
-
-server_config = {
-    "command": _cmd_callback
-}
-```
-
-The `port` argument will be passed to the callable. This is a simple form of dependency
-injection that helps us add more parameters in the future without breaking backwards
-compatibility.
-
-#### Available arguments
-
-Unless otherwise documented for specific options, the arguments available for
-callables are:
-
-1. **port**
-   The TCP port on which the server should listen, or is listening.
-   This is 0 if a Unix socket is used instead of TCP.
-2. **unix_socket**
-   The path of a Unix socket on which the server should listen, or is listening.
-   This is an empty string if a TCP socket is used.
-3. **base_url**
-   The base URL of the notebook
-
-If any of the returned strings, lists or dictionaries contain strings
-of form `{<argument-name>}`, they will be replaced with the value
-of the argument. For example, if your function is:
-
-```python
-def _openrefine_cmd():
-    return ["openrefine", "-p", "{port}"]
-```
-
-The `{port}` will be replaced with the appropriate port before
-the command is started
-
 ## Specifying config via traitlets
 
 [Traitlets](https://traitlets.readthedocs.io/) are the configuration