Skip to content

Commit

Permalink
Autogenerate ServerProcess documentation instead of duplicating it
Browse files Browse the repository at this point in the history 
Avoid duplication in documentation
  • Loading branch information
@manics
manics committed Oct 27, 2024
1 parent fef3695 commit 7c4002b
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 223 deletions.
60 changes: 60 additions & 0 deletions docs/extensions/serverprocess_documenter.py
View file
Original file line number Diff line number Diff line change
@@ -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,
}
8 changes: 8 additions & 0 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"]
Expand Down
225 changes: 2 additions & 223 deletions docs/source/server-process.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 7c4002b

Please sign in to comment.