Merge pull request #1097 from mathbunnyru/asalikhov/improve_docs

Improve documentation

Author: parente

docs/contributing/features.md

@@ -25,9 +25,9 @@ If there's agreement that the feature belongs in one or more of the core stacks:
 
 1. Implement the feature in a local clone of the `jupyter/docker-stacks` project.
 2. Please build the image locally before submitting a pull request. Building the image locally shortens the debugging cycle by taking some load off [Travis CI](http://travis-ci.org/), which graciously provides free build services for open source projects like this one.  If you use `make`, call:
-```
-make build/somestack-notebook
-```
+    ```bash
+    make build/somestack-notebook
+    ```
 3. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
 4. Watch for Travis to report a build success or failure for your PR on GitHub.
 5. Discuss changes with the maintainers and address any build issues.

docs/contributing/packages.md

@@ -7,9 +7,9 @@ Please follow the process below to update a package version:
 1. Locate the Dockerfile containing the library you wish to update (e.g., [base-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/base-notebook/Dockerfile), [scipy-notebook/Dockerfile](https://github.com/jupyter/docker-stacks/blob/master/scipy-notebook/Dockerfile))
 2. Adjust the version number for the package. We prefer to pin the major and minor version number of packages so as to minimize rebuild side-effects when users submit pull requests (PRs). For example, you'll find the Jupyter Notebook package, `notebook`, installed using conda with `notebook=5.4.*`.
 3. Please build the image locally before submitting a pull request. Building the image locally shortens the debugging cycle by taking some load off [Travis CI](http://travis-ci.org/), which graciously provides free build services for open source projects like this one. If you use `make`, call:
-```
-make build/somestack-notebook
-```
+    ```bash
+    make build/somestack-notebook
+    ```
 4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
 5. Watch for Travis to report a build success or failure for your PR on GitHub.
 6. Discuss changes with the maintainers and address any build issues. Version conflicts are the most common problem. You may need to upgrade additional packages to fix build failures.

docs/contributing/stacks.md

@@ -13,13 +13,13 @@ This approach mirrors how we build and share the core stack images. Feel free to
 
 First, install [cookiecutter](https://github.com/audreyr/cookiecutter) using pip or conda:
 
-```
+```bash
 pip install cookiecutter   # or conda install cookiecutter
 ```
 
 Run the cookiecutter command pointing to the [jupyter/cookiecutter-docker-stacks](https://github.com/jupyter/cookiecutter-docker-stacks) project on GitHub.
 
-```
+```bash
 cookiecutter https://github.com/jupyter/cookiecutter-docker-stacks.git
 ```
 

docs/contributing/tests.md

@@ -13,10 +13,10 @@ Please follow the process below to add new tests:
 1. If the test should run against every image built, add your test code to one of the modules in [test/](https://github.com/jupyter/docker-stacks/tree/master/test) or create a new module.
 2. If your test should run against a single image, add your test code to one of the modules in `some-notebook/test/` or create a new module.
 3. Build one or more images you intend to test and run the tests locally. If you use `make`, call:
-```
-make build/somestack-notebook
-make test/somestack-notebook
-```
+    ```bash
+    make build/somestack-notebook
+    make test/somestack-notebook
+    ```
 4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes.
 5. Watch for Travis to report a build success or failure for your PR on GitHub.
-6. Discuss changes with the maintainers and address any issues running the tests on Travis.
+6. Discuss changes with the maintainers and address any issues running the tests on Travis.

docs/using/common.md

@@ -8,13 +8,13 @@ This page describes the options supported by the startup script as well as how t
 
 You can pass [Jupyter command line options](https://jupyter.readthedocs.io/en/latest/projects/jupyter-command.html) to the `start-notebook.sh` script when launching the container. For example, to secure the Notebook server with a custom password hashed using `IPython.lib.passwd()` instead of the default token, you can run the following:
 
-```
+```bash
 docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp.password='sha1:74ba40f8a388:c913541b7ee99d15d5ed31d4226bf7838f83a50e'
 ```
 
 For example, to set the base URL of the notebook server, you can run the following:
 
-```
+```bash
 docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp.base_url=/some/path
 ```
 
@@ -54,7 +54,7 @@ script for execution details.
 
 You may mount SSL key and certificate files into a container and configure Jupyter Notebook to use them to accept HTTPS connections. For example, to mount a host folder containing a `notebook.key` and `notebook.crt` and use them, you might run the following:
 
-```
+```bash
 docker run -d -p 8888:8888 \
     -v /some/host/folder:/etc/ssl/notebook \
     jupyter/base-notebook start-notebook.sh \
@@ -64,7 +64,7 @@ docker run -d -p 8888:8888 \
 
 Alternatively, you may mount a single PEM file containing both the key and certificate. For example:
 
-```
+```bash
 docker run -d -p 8888:8888 \
     -v /some/host/folder/notebook.pem:/etc/ssl/notebook.pem \
     jupyter/base-notebook start-notebook.sh \
@@ -85,13 +85,13 @@ For additional information about using SSL, see the following:
 
 The `start-notebook.sh` script actually inherits most of its option handling capability from a more generic `start.sh` script. The `start.sh` script supports all of the features described above, but allows you to specify an arbitrary command to execute. For example, to run the text-based `ipython` console in a container, do the following:
 
-```
+```bash
 docker run -it --rm jupyter/base-notebook start.sh ipython
 ```
 
 Or, to run JupyterLab instead of the classic notebook, run the following:
 
-```
+```bash
 docker run -it --rm -p 8888:8888 jupyter/base-notebook start.sh jupyter lab
 ```
 
@@ -107,7 +107,7 @@ The default Python 3.x [Conda environment](http://conda.pydata.org/docs/using/en
 
 The `jovyan` user has full read/write access to the `/opt/conda` directory. You can use either `conda` or `pip` to install new packages without any additional permissions.
 
-```
+```bash
 # install a package into the default (python 3.x) environment
 pip install some-package
 conda install some-package

docs/using/recipes.md

@@ -17,7 +17,7 @@ orchestrator config.
 
 For example:
 
-```
+```bash
 docker run -it -e GRANT_SUDO=yes --user root jupyter/minimal-notebook
 ```
 
@@ -75,7 +75,7 @@ Python 2.x was removed from all images on August 10th, 2017, starting in tag `cc
 add a Python 2.x environment by defining your own Dockerfile inheriting from one of the images like
 so:
 
-```
+```dockerfile
 # Choose your desired base image
 FROM jupyter/scipy-notebook:latest
 
@@ -103,7 +103,7 @@ Ref:
 The default version of Python that ships with conda/ubuntu may not be the version you want.
 To add a conda environment with a different version and make it accessible to Jupyter, the instructions are very similar to Python 2.x but are slightly simpler (no need to switch to `root`):
 
-```
+```dockerfile
 # Choose your desired base image
 FROM jupyter/minimal-notebook:latest
 
@@ -168,12 +168,12 @@ ENTRYPOINT ["jupyter", "lab", "--ip=0.0.0.0", "--allow-root"]
 ```
 
 And build the image as:
-```
+```bash
 docker build -t jupyter/scipy-dasklabextension:latest .
 ```
 
 Once built, run using the command:
-```
+```bash
 docker run -it --rm -p 8888:8888 -p 8787:8787 jupyter/scipy-dasklabextension:latest
 ```
 
@@ -194,7 +194,7 @@ Ref:
 [RISE](https://github.com/damianavila/RISE) allows via extension to create live slideshows of your
 notebooks, with no conversion, adding javascript Reveal.js:
 
-```
+```bash
 # Add Live slideshows with RISE
 RUN conda install -c damianavila82 rise
 ```
@@ -207,7 +207,7 @@ Credit: [Paolo D.](https://github.com/pdonorio) based on
 You need to install conda's gcc for Python xgboost to work properly. Otherwise, you'll get an
 exception about libgomp.so.1 missing GOMP_4.0.
 
-```
+```bash
 %%bash
 conda install -y gcc
 pip install xgboost
@@ -320,8 +320,8 @@ Credit: [Justin Tyberg](https://github.com/jtyberg), [quanghoc](https://github.c
 To use a specific version of JupyterHub, the version of `jupyterhub` in your image should match the
 version in the Hub itself.
 
-```
-FROM  jupyter/base-notebook:5ded1de07260
+```dockerfile
+FROM jupyter/base-notebook:5ded1de07260
 RUN pip install jupyterhub==0.8.0b1
 ```
 
@@ -383,7 +383,7 @@ Ref:
 
 ### Using Local Spark JARs
 
-```
+```python
 import os
 os.environ['PYSPARK_SUBMIT_ARGS'] = '--jars /home/jovyan/spark-streaming-kafka-assembly_2.10-1.6.1.jar pyspark-shell'
 import pyspark
@@ -412,7 +412,7 @@ Ref:
 
 ### Use jupyter/all-spark-notebooks with an existing Spark/YARN cluster
 
-```
+```dockerfile
 FROM jupyter/all-spark-notebook
 
 # Set env vars for pydoop
@@ -488,21 +488,21 @@ convenient to launch the server without a password or token. In this case, you s
 
 For jupyterlab:
 
-```
+```bash
 docker run jupyter/base-notebook:6d2a05346196 start.sh jupyter lab --LabApp.token=''
 ```
 
 For jupyter classic:
 
-```
+```bash
 docker run jupyter/base-notebook:6d2a05346196 start.sh jupyter notebook --NotebookApp.token=''
 ```
 
 ## Enable nbextension spellchecker for markdown (or any other nbextension)
 
 NB: this works for classic notebooks only
 
-```
+```dockerfile
 # Update with your base image of choice
 FROM jupyter/minimal-notebook:latest
 
@@ -521,7 +521,7 @@ Ref:
 
 Using `auto-sklearn` requires `swig`, which the other notebook images lack, so it cant be experimented with. Also, there is no Conda package for `auto-sklearn`.
 
-```
+```dockerfile
 ARG BASE_CONTAINER=jupyter/scipy-notebook
 FROM jupyter/scipy-notebook:latest
 

docs/using/specifics.md

@@ -112,8 +112,8 @@ Connection to Spark Cluster on **[Standalone Mode](https://spark.apache.org/docs
 2. Run the Docker container with `--net=host` in a location that is network addressable by all of
    your Spark workers. (This is a [Spark networking
    requirement](http://spark.apache.org/docs/latest/cluster-overview.html#components).)
-    * NOTE: When using `--net=host`, you must also use the flags `--pid=host -e
-      TINI_SUBREAPER=true`. See https://github.com/jupyter/docker-stacks/issues/64 for details.
+   * NOTE: When using `--net=host`, you must also use the flags `--pid=host -e
+   TINI_SUBREAPER=true`. See https://github.com/jupyter/docker-stacks/issues/64 for details.
 
 **Note**: In the following examples we are using the Spark master URL `spark://master:7077` that shall be replaced by the URL of the Spark master.
 

examples/docker-compose/README.md

@@ -12,7 +12,7 @@ See the [installation instructions](https://docs.docker.com/engine/installation/
 
 Build and run a `jupyter/minimal-notebook` container on a VirtualBox VM on local desktop.
 
-```
+```bash
 # create a Docker Machine-controlled VirtualBox VM
 bin/vbox.sh mymachine
 
@@ -28,7 +28,7 @@ notebook/up.sh
 
 To stop and remove the container:
 
-```
+```bash
 notebook/down.sh
 ```
 
@@ -39,14 +39,14 @@ notebook/down.sh
 
 You can customize the docker-stack notebook image to deploy by modifying the `notebook/Dockerfile`.  For example, you can build and deploy a `jupyter/all-spark-notebook` by modifying the Dockerfile like so:
 
-```
+```dockerfile
 FROM jupyter/all-spark-notebook:55d5ca6be183
 ...
 ```
 
 Once you modify the Dockerfile, don't forget to rebuild the image.
 
-```
+```bash
 # activate the docker machine
 eval "$(docker-machine env mymachine)"
 
@@ -57,14 +57,14 @@ notebook/build.sh
 
 Yes. Set environment variables to specify unique names and ports when running the `up.sh` command.
 
-```
+```bash
 NAME=my-notebook PORT=9000 notebook/up.sh
 NAME=your-notebook PORT=9001 notebook/up.sh
 ```
 
 To stop and remove the containers:
 
-```
+```bash
 NAME=my-notebook notebook/down.sh
 NAME=your-notebook notebook/down.sh
 ```
@@ -78,7 +78,7 @@ The `up.sh` creates a Docker volume named after the notebook container with a `-
 
 Yes. Set the `WORK_VOLUME` environment variable to the same value for each notebook.
 
-```
+```bash
 NAME=my-notebook PORT=9000 WORK_VOLUME=our-work notebook/up.sh
 NAME=your-notebook PORT=9001 WORK_VOLUME=our-work notebook/up.sh
 ```
@@ -87,7 +87,7 @@ NAME=your-notebook PORT=9001 WORK_VOLUME=our-work notebook/up.sh
 
 To run the notebook server with a self-signed certificate, pass the `--secure` option to the `up.sh` script.  You must also provide a password, which will be used to secure the notebook server.  You can specify the password by setting the `PASSWORD` environment variable, or by passing it to the `up.sh` script.  
 
-```
+```bash
 PASSWORD=a_secret notebook/up.sh --secure
 
 # or
@@ -103,15 +103,15 @@ This example includes the `bin/letsencrypt.sh` script, which runs the `letsencry
 
 The following command will create a certificate chain and store it in a Docker volume named `mydomain-secrets`.
 
-```
+```bash
 FQDN=host.mydomain.com [email protected] \
   SECRETS_VOLUME=mydomain-secrets \
   bin/letsencrypt.sh
 ```
 
 Now run `up.sh` with the `--letsencrypt` option.  You must also provide the name of the secrets volume and a password.
 
-```
+```bash
 PASSWORD=a_secret SECRETS_VOLUME=mydomain-secrets notebook/up.sh --letsencrypt
 
 # or
@@ -120,7 +120,7 @@ notebook/up.sh --letsencrypt --password a_secret --secrets mydomain-secrets
 
 Be aware that Let's Encrypt has a pretty [low rate limit per domain](https://community.letsencrypt.org/t/public-beta-rate-limits/4772/3) at the moment.  You can avoid exhausting your limit by testing against the Let's Encrypt staging servers.  To hit their staging servers, set the environment variable `CERT_SERVER=--staging`.
 
-```
+```bash
 FQDN=host.mydomain.com [email protected] \
   CERT_SERVER=--staging \
   bin/letsencrypt.sh
@@ -134,13 +134,13 @@ Yes, you should be able to deploy to any Docker Machine-controlled host.  To mak
 
 To create a Docker machine using a VirtualBox VM on local desktop:
 
-```
+```bash
 bin/vbox.sh mymachine
 ```
 
 To create a Docker machine using a virtual device on IBM SoftLayer:
 
-```
+```bash
 export SOFTLAYER_USER=my_softlayer_username
 export SOFTLAYER_API_KEY=my_softlayer_api_key
 export SOFTLAYER_DOMAIN=my.domain