Merge pull request #348 from mwouts/docs_use_myst_parser

Render .md files on RTD with MyST-parser

Author: kevin-bates

docs/environment.yml

@@ -6,8 +6,8 @@ dependencies:
   - python=3.7
   - sphinx
   - sphinx_rtd_theme
-  - recommonmark
   - pillow
   - pip
   - pip:
-      - readthedocs-sphinx-ext
+      - myst_parser
+      - readthedocs-sphinx-ext

docs/source/conf.py

@@ -13,9 +13,6 @@
 import os
 import shlex
 
-# Needed for conversion from markdown to html
-import recommonmark.parser
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -35,17 +32,12 @@
     'sphinx.ext.napoleon',
     "sphinx.ext.extlinks",
     "sphinx.ext.viewcode",
-    "recommonmark"
+    "myst_parser"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# Jupyter uses recommonmark's parser to convert markdown
-source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
-}
-
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']

docs/source/config-options.md

@@ -1,4 +1,4 @@
-## Configuration options
+# Configuration options
 
 The kernel gateway adheres to the [Jupyter common configuration approach](https://jupyter.readthedocs.io/en/latest/projects/config.html). You can configure an instance of the kernel gateway using:
 

docs/source/devinstall.md

@@ -1,14 +1,14 @@
-## Development Workflow
+# Development Workflow
 
 This document includes instructions for setting up a development environment
 for the Jupyter Kernel Gateway. It also includes common steps in the developer
 workflow such as running tests, building docs, updating specs, etc.
 
-### Prerequisites
+## Prerequisites
 
 Install [miniconda](https://conda.io/miniconda.html) and GNU make on your system.
 
-### Clone the repo
+## Clone the repo
 
 Clone this repository in a local directory.
 
@@ -21,7 +21,7 @@ cd !$
 git clone https://github.com/jupyter/kernel_gateway.git
 ```
 
-### Build a conda environment
+## Build a conda environment
 
 Build a Python 3 conda environment containing the necessary dependencies for
 running the kernel gateway, running tests, and building documentation.
@@ -30,15 +30,15 @@ running the kernel gateway, running tests, and building documentation.
 make env
 ```
 
-### Run the tests
+## Run the tests
 
 Run the tests suite.
 
 ```bash
 make test
 ```
 
-### Run the gateway server
+## Run the gateway server
 
 Run an instance of the kernel gateway server in [`jupyter-websocket` mode](websocket-mode.md).
 
@@ -56,15 +56,15 @@ make dev-http
 
 Then access the running server at the URL printed in the console.
 
-### Build the docs
+## Build the docs
 
 Run Sphinx to build the HTML documentation.
 
 ```bash
 make docs
 ```
 
-### Update the Swagger API spec
+## Update the Swagger API spec
 
 After modifying any of the APIs in `jupyter-websocket` mode, you must update the project's Swagger API specification.
 

docs/source/features.md

@@ -1,4 +1,4 @@
-## Features
+# Features
 
 The Jupyter Kernel Gateway has the following features:
 

docs/source/getting-started.md

@@ -1,9 +1,9 @@
-## Getting started
+# Getting started
 
 This document describes some of the basics of installing and running the
 Jupyter Kernel Gateway.
 
-### Using pip
+## Using pip
 
 We make stable releases of the kernel gateway to PyPI. You can use `pip` to install the latest version along with its dependencies.
 
@@ -19,7 +19,7 @@ Once installed, you can use the `jupyter` CLI to run the server.
 jupyter kernelgateway
 ```
 
-### Using conda
+## Using conda
 
 You can install the kernel gateway using conda as well.
 
@@ -29,7 +29,7 @@ conda install -c conda-forge jupyter_kernel_gateway
 
 Once installed, you can use the `jupyter` CLI to run the server as shown above.
 
-### Using a docker-stacks image
+## Using a docker-stacks image
 
 You can add the kernel gateway to any [docker-stacks](https://github.com/jupyter/docker-stacks) image by writing a Dockerfile patterned after the following example:
 

docs/source/http-mode.md

@@ -1,4 +1,4 @@
-## `notebook-http` Mode
+# `notebook-http` Mode
 
 The `KernelGatewayApp.api` command line argument can be set to `kernel_gateway.notebook_http`. This mode, or *personality*, has the kernel gateway expose annotated cells in the `KernelGatewayApp.seed_uri` notebook as HTTP resources.
 
@@ -21,7 +21,7 @@ print("I'm cell #1")
 print("I'm cell #2")
 ```
 
-### Getting the Request Data
+## Getting the Request Data
 
 Before the gateway invokes an annotated cell, it sets the value of a global notebook variable named `REQUEST` to a JSON string containing information about the request. You may parse this string to access the request properties.
 
@@ -46,7 +46,7 @@ The `REQUEST` object currently contains the following properties:
 * `path` - An object of key-value pairs representing path parameters and their values.
 * `headers` - An object of key-value pairs where a key is a HTTP header name and a value is the HTTP header value. If there are multiple values are specified for a  header, the value will be an array.
 
-#### Request Content-Type and Request Body Processing
+### Request Content-Type and Request Body Processing
 
 If the HTTP request to the kernel gateway has a `Content-Type` header the value of `REQUEST.body` may change. Below is the list of outcomes for various mime-types:
 
@@ -55,7 +55,7 @@ If the HTTP request to the kernel gateway has a `Content-Type` header the value
 * `text/plain` -  The `REQUEST.body` will be the string value of the body
 * All other types will be sent as strings
 
-### Setting the Response Body
+## Setting the Response Body
 
 The response from an annotated cell may be set in one of two ways:
 
@@ -70,7 +70,7 @@ In both cases, the response defaults to status `200 OK` and `Content-Type: text/
 
 See the [api_intro.ipynb](https://github.com/jupyter/kernel_gateway/blob/master/etc/api_examples/api_intro.ipynb) notebook for basic request and response examples.
 
-### Setting the Response Status and Headers
+## Setting the Response Status and Headers
 
 Annotated cells may have an optional metadata companion cell that sets the HTTP response status and headers. Consider this Python cell that creates a person entry in a database table and returns the new row ID in a JSON object:
 
@@ -107,13 +107,13 @@ Content-Type: application/json
 
 See the [setting_response_metadata.ipynb](https://github.com/jupyter/kernel_gateway/blob/master/etc/api_examples/setting_response_metadata.ipynb) notebook for examples of setting response metadata.
 
-### Swagger Spec
+## Swagger Spec
 
 The resource `/_api/spec/swagger.json` is automatically generated from the notebook used to define the HTTP API. The response is a simple Swagger spec which can be used with the [Swagger editor](http://editor.swagger.io/#), a [Swagger ui](https://github.com/swagger-api/swagger-ui), or with any other Swagger-aware tool.
 
 Currently, every response is listed as having a status of `200 OK`.
 
-### Running
+## Running
 
 The minimum number of arguments needed to run in HTTP mode are `--KernelGatewayApp.api=kernel_gateway.notebook_http` and `--KernelGatewayApp.seed_uri=some/notebook/file.ipynb`.
 

docs/source/plug-in.md

@@ -1,4 +1,4 @@
-## Developing New Modes
+# Developing New Modes
 
 The `KernelGatewayApp.api` can be set to the name of any module in the Python path supplying a personality. This allows for alternate kernel communications mechanisms.
 
@@ -36,5 +36,4 @@ def create_personality(self, parent):
     return TemplatePersonality(parent=parent)
 ```
 
-Provided personalities include
-  [kernel_gateway.jupyter_websocket](_modules/kernel_gateway/jupyter_websocket.html) and   [kernel_gateway.notebook_http](_modules/kernel_gateway/notebook_http.html).
+Provided personalities include [kernel_gateway.jupyter_websocket](websocket-mode.md) and [kernel_gateway.notebook_http](http-mode.md).

docs/source/summary-changes.md

@@ -3,7 +3,7 @@
 See `git log` for a more detailed summary of changes.
 ## 2.4
 
-## 2.4.0 (2019-08-11)
+### 2.4.0 (2019-08-11)
 
 * [PR-323](https://github.com/jupyter/kernel_gateway/pull/323): Update handler not use deprecated maybe_future call
 * [PR-322](https://github.com/jupyter/kernel_gateway/pull/322): Update handler compatibility with tornado/pyzmq updates

docs/source/troubleshooting.md

@@ -1,6 +1,6 @@
-## Troubleshooting
+# Troubleshooting
 
-### I can't access kernel gateway in my Docker container.
+## I can't access kernel gateway in my Docker container.
 
 The kernel gateway server listens on port 8888 by default. Make sure this internal port is exposed on an external port when starting the container. For example, if you run:
 
@@ -10,6 +10,6 @@ docker run -it --rm -p 9000:8888 jupyter/minimal-kernel
 
 you can access your kernel gateway on the IP address of your Docker host an port 9000.
 
-### Kernel gateway raises an error when I use `notebook-http` mode.
+## Kernel gateway raises an error when I use `notebook-http` mode.
 
 The `notebook-http` mode publishes a web API defined by annotations and code in a notebook. Make sure you are specifying a path or URL of a notebook (`*.ipynb`) file when you launch the kernel gateway in this mode. Set the `--KernelGatewayApp.seed_uri` command line parameter or `KG_SEED_URI` environment variable to do so.

docs/source/uses.md

@@ -1,4 +1,4 @@
-## Use Cases
+# Use Cases
 
 The Jupyter Kernel Gateway makes possible the following novel uses of kernels:
 

docs/source/websocket-mode.md

@@ -1,15 +1,15 @@
-## `jupyter-websocket` Mode
+# `jupyter-websocket` Mode
 
 The `KernelGatewayApp.api` command line argument defaults to `kernel_gateway.jupyter_websocket`. This mode, or *personality*, has the kernel gateway expose:
 
 1. a superset of the HTTP API provided by the Jupyter Notebook server, and
 2. the equivalent Websocket API implemented by the Jupyter Notebook server.
 
-### HTTP Resources
+## HTTP Resources
 
 The HTTP API consists of kernel, session, monitoring, and metadata resources. All of these are documented in a [swagger.yaml](https://github.com/jupyter/kernel_gateway/blob/master/kernel_gateway/jupyter_websocket/swagger.yaml) file. You can use the [Swagger UI](http://petstore.swagger.io) to interact with a running instance of the kernel gateway by pointing the tool to the `/api/swagger.json` resource.
 
-### Websocket Resources
+## Websocket Resources
 
 The `/api/kernels/{kernel_id}/channels` resource multiplexes the [Jupyter kernel messaging protocol](https://jupyter-client.readthedocs.io/en/latest/messaging.html) over a single Websocket connection.
 

requirements-doc.txt

@@ -1,3 +1,3 @@
 sphinx_rtd_theme
 sphinx
-recommonmark
+myst-parser