docs: convert .rst to MyST based markdown files

.github/workflows/publish.yaml

@@ -11,15 +11,13 @@ on:
       - "docs/**"
       - "contrib/**"
       - "**.md"
-      - "**.rst"
       - ".github/workflows/*"
       - "!.github/workflows/publish.yaml"
   push:
     paths-ignore:
       - "docs/**"
       - "contrib/**"
       - "**.md"
-      - "**.rst"
       - ".github/workflows/*"
       - "!.github/workflows/publish.yaml"
     branches-ignore:

.github/workflows/test.yaml

@@ -9,15 +9,13 @@ on:
       - "docs/**"
       - "contrib/**"
       - "**.md"
-      - "**.rst"
       - ".github/workflows/*"
       - "!.github/workflows/test.yaml"
   push:
     paths-ignore:
       - "docs/**"
       - "contrib/**"
       - "**.md"
-      - "**.rst"
       - ".github/workflows/*"
       - "!.github/workflows/test.yaml"
     branches-ignore:

docs/source/arbitrary-ports-hosts.md

@@ -0,0 +1,86 @@
+(arbitrary-ports)=
+
+# Accessing Arbitrary Ports or Hosts
+
+If you already have a server running on localhost listening on
+a port, you can access it through the notebook at
+`<notebook-base>/proxy/<port>`.
+The URL will be rewritten to remove the above prefix.
+
+You can disable URL rewriting by using
+`<notebook-base>/proxy/absolute/<port>` so your server will receive the full
+URL in the request.
+
+This works for all ports listening on the local machine.
+
+You can also specify arbitrary hosts in order to proxy traffic from
+another machine on the network `<notebook-base>/proxy/<host>:<port>`.
+
+For security reasons the host must match an entry in the `host_allowlist` in your configuration.
+
+## With JupyterHub
+
+Let's say you are using a JupyterHub set up on a remote machine, and you have a
+process running on that machine listening on port 8080. If your hub URL is
+`myhub.org`, each user can access the service running on port 8080 with the URL
+`myhub.org/hub/user-redirect/proxy/8080`. The `user-redirect` will make sure
+that:
+
+1. It provides a redirect to the correct URL for the particular
+   user who is logged in.
+2. If a user is not logged in, it'll present them with a login
+   screen. They'll be redirected there after completing authentication.
+
+You can also set `c.Spawner.default_url` to `/proxy/8080` to have
+users be shown to your application directly after logging in -
+without ever seeing the notebook interface.
+
+## Without JupyterHub
+
+A very similar set up works when you don't use JupyterHub. You
+can construct the URL with `<notebook-url>/proxy/<port>`.
+
+If your notebook url is `http://localhost:8888` and you have
+a process running listening on port 8080, you can access it with
+the URL `http://localhost:8888/proxy/8080`.
+
+This is mostly useful for testing, since you can normally just
+access services on your local machine directly.
+
+## From Notebook Extension
+
+If you have a client side extension for the classic Jupyter Notebook
+interface (nbextension), you can construct the URL for accessing
+your service in this way:
+
+```js
+define(["base/js/utils"], function (utils) {
+  // Get base URL of current notebook server
+  var base_url = utils.get_body_data("baseUrl");
+
+  // Construct URL of our proxied service
+  var service_url = base_url + "proxy/" + port;
+
+  // Do stuff with your service_url
+});
+```
+
+You can then make HTTP / Websocket requests as you wish from your
+code.
+
+## From JupyterLab Extension
+
+Accessing your service from a JupyterLab extension is similar to
+accessing it from a classic notebook extension.
+
+```typescript
+import { PageConfig } from "@jupyterlab/coreutils";
+
+// Get base URL of current notebook server
+let base_url = PageConfig.getBaseUrl();
+
+// Construct URL of our proxied service
+let service_url = base_url + "proxy/" + port;
+
+// Do stuff with your service_url
+```

docs/source/conf.py

@@ -25,7 +25,7 @@
     "sphinxext.rediraffe",
 ]
 root_doc = "index"
-source_suffix = [".md", ".rst"]
+source_suffix = [".md"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 

docs/source/convenience/new.md

@@ -0,0 +1,19 @@
+(convenience:new)=
+
+# Making a new convenience package
+
+There is a [cookiecutter](https://github.com/cookiecutter/cookiecutter)
+template provided in this repo that can be used to make new packages.
+
+```bash
+pip install cookiecutter
+cookiecutter contrib/template -o contrib/
+```
+
+This should ask you a bunch of questions, and generate a directory
+named after your project with a python package. From there, you should:
+
+1. Edit the `__init__.py` file to fill in the command used to start your
+   process, any environment variables, and title of the launcher icon.
+2. (Optionally) Add a square svg icon for your launcher in the `icons`
+   subfolder, with the same name as your project.

docs/source/convenience/packages/theia.md

@@ -0,0 +1,69 @@
+# Theia IDE
+
+[Theia](https://theia-ide.org/) is a configurable web based IDE
+built with components from [Visual Studio Code](https://code.visualstudio.com/).
+
+This package is a plugin for [jupyter-server-proxy](https://jupyter-server-proxy.readthedocs.io/)
+that lets you run an instance of theia alongside your notebook, primarily
+in a JupyterHub / Binder environment.
+
+## Installing Theia
+
+1. [Install the Yarn package manager](https://classic.yarnpkg.com/en/docs/install/) with one of the available
+   methods.
+
+2. Theia is highly configurable, so you need to decide which features you want
+   in your theia install. Make a `package.json` with the list of extensions you want,
+   following [the instructions here](https://theia-ide.org/docs/composing_applications/).
+
+   Here is an example:
+
+   ```js
+   {
+     "private": true,
+     "dependencies": {
+         "@theia/callhierarchy": "latest",
+         "@theia/editor-preview": "latest",
+         "@theia/file-search": "latest",
+         "@theia/git": "latest",
+         "@theia/json": "latest",
+         "@theia/languages": "latest",
+         "@theia/markers": "latest",
+         "@theia/merge-conflicts": "latest",
+         "@theia/messages": "latest",
+         "@theia/mini-browser": "latest",
+         "@theia/monaco": "latest",
+         "@theia/navigator": "latest",
+         "@theia/outline-view": "latest",
+         "@theia/preferences": "latest",
+         "@theia/preview": "latest",
+         "@theia/python": "latest",
+         "@theia/search-in-workspace": "latest",
+         "@theia/terminal": "latest",
+         "@theia/textmate-grammars": "latest",
+         "@theia/typescript": "latest",
+         "typescript": "latest",
+         "yarn": "^1.12.3"
+     },
+     "devDependencies": {
+         "@theia/cli": "latest"
+     }
+   }
+   ```
+
+3. Run the following commands in the same location as your package.json file
+   to install all packages & build theia.
+
+   ```bash
+   yarn
+   yarn theia build
+   ```
+
+   This should set up theia to run and be built.
+
+4. Add the `node_modules/.bin` directory to your `$PATH`, so `jupyter-theia-proxy` can
+   find the `theia` command.
+
+   ```bash
+   export PATH="$(pwd)/node_modules/.bin:${PATH}"
+   ```

docs/source/examples.md

@@ -0,0 +1,14 @@
+(examples)=
+
+# Examples
+
+If you are looking for examples on how to configure `jupyter-server-proxy`, you might want to check existing
+projects on GitHub, such as:
+
+- [jupyter-pgweb-proxy](https://github.com/illumidesk/jupyter-pgweb-proxy): Run [pgweb](https://github.com/sosedoff/pgweb) (cross-platform PostgreSQL client)
+- [jupyter-pluto-proxy](https://github.com/illumidesk/jupyter-pluto-proxy): Run [Pluto.jl](https://github.com/fonsp/Pluto.jl) (notebooks for Julia)
+- [jupyterserverproxy-openrefine](https://github.com/psychemedia/jupyterserverproxy-openrefine): Run [OpenRefine](https://openrefine.org/) (tool for working with messy data)
+- [gator](https://github.com/mamba-org/gator): Run the Mamba Navigator (JupyterLab-based standalone application)
+
+Projects can also add the `jupyter-server-proxy` topic to the GitHub repository to make it more discoverable:
+[https://github.com/topics/jupyter-server-proxy](https://github.com/topics/jupyter-server-proxy)