Switch to sphinx+rtd for documentation

- mkdocs doesn't support GFMD, so is a different dialect
- recommonmark seems abandoned
- Couldn't get m2r to work

So RST + Sphinx it is!

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = TheLittlestJupyterHub
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/admin.rst

@@ -1,4 +1,5 @@
-# Administrative Access
+Administrative Access
+---------------------
 
 In The Littlest JupyterHub, we try to allow users to do as many administrative
 tasks as possible within JupyterHub itself. Admin users can:
@@ -6,30 +7,30 @@ tasks as possible within JupyterHub itself. Admin users can:
 1. Have full root access with passwordless `sudo`
 2. Install systemwide packages with `apt`
 3. Install `conda` / `pip` packages for all JupyterHub
-4. Change amount of RAM / CPU available to each user
+4. Change amount of RAM / CPU available to each user and more!
-and more!
 
 By default, there are no admin users. You should add some after installation.
 
-## Adding admin users
+Adding admin users
+==================
 
-Admin users are specified in the [YAML](https://en.wikipedia.org/wiki/YAML)
+Admin users are specified in the `YAML <https://en.wikipedia.org/wiki/YAML>`_
-config file at `/opt/tljh/config.yaml`.
+config file at ``/opt/tljh/config.yaml``.
 
-1. Open the `config.yaml` file for editing.
+1. Open the ``config.yaml`` file for editing.
 
-   ```bash
+   .. code-block:: bash
-   sudo nano /opt/tljh/config.yaml
+
-   ```
+      sudo nano /opt/tljh/config.yaml
 
 2. Add usernames that should have admin access.
 
-   ```yaml
+   .. code-block:: yaml
-   users:
+
-     admin:
+      users:
-       - user1
+        admin:
-       - user2
+          - user1
-   ```
+          - user2
 
    Be careful around the syntax - indentation matters, and you should be using
    spaces and not tabs.
@@ -40,13 +41,13 @@ config file at `/opt/tljh/config.yaml`.
 3. When you are sure the format is ok, restart JupyterHub to let the config take
    effect.
 
-   ```bash
+   .. code-block:: bash
-   sudo systemctl restart jupyterhub
+
-   ```
+      sudo systemctl restart jupyterhub
 
 This should give you admin access from JupyterHub! You can verify this by:
 
-1. Opening a Terminal in your JupyterHub and checking if `sudo` works
+1. Opening a Terminal in your JupyterHub and checking if ``sudo`` works
-2. Opening your JupyterHub `Control Panel` and checking for the **Admin** tab
+2. Opening your JupyterHub ``Control Panel`` and checking for the **Admin** tab
 
 From now on, you can use the JupyterHub to do most configuration changes.

docs/conf.py

@@ -0,0 +1,32 @@
+from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
+
+# Support markdown too
+source_suffix = ['.rst']
+
+project = 'The Littlest JupyterHub'
+copyright = '2018, JupyterHub Team'
+author = 'JupyterHub Team'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = 'v0.1'
+
+# The master toctree document.
+master_doc = 'index'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/index.md

@@ -1,24 +0,0 @@
-# The Littlest JupyterHub
-
-A simple [JupyterHub](https://github.com/jupyterhub/jupyterhub) distribution for
-a small (0-50) number of users on a single server.
-
-## Quick Start
-
-On a fresh Ubuntu 18.04 server, you can install The Littlest JupyterHub with:
-
-```bash
-curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/installer/install.bash | sudo bash -
-```
-
-This takes 2-5 minutes to run. When completed, you can access your new JupyterHub
-at the public IP of your server!
-
-If this installation method (`curl <arbitrary-url> | sudo bash -`)
-makes you nervous, check out the [other installation methods](install.md) we support!
-
-## Table of Contents
-
-- [Server requirements](requirements.md)
-- [Installation](install.md)
-- [Administrative Access](admin.md)

docs/index.rst

@@ -0,0 +1,27 @@
+The Littlest JupyterHub
+-----------------------
+
+A simple `JupyterHub <https://github.com/jupyterhub/jupyterhub>`_ distribution for
+a small (0-50) number of users on a single server.
+
+Quick Start
+===========
+
+On a fresh Ubuntu 18.04 server, you can install The Littlest JupyterHub with:
+
+.. code-block:: bash
+
+   curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/installer/install.bash | sudo bash -
+
+This takes 2-5 minutes to run. When completed, you can access your new JupyterHub
+at the public IP of your server!
+
+If this installation method (``curl <arbitrary-url> | sudo bash -``)
+makes you nervous, check out the :ref:`other installation methods <installation>` we support!
+
+.. toctree::
+   :maxdepth: 1
+
+   requirements
+   install
+   admin

docs/install.rst

@@ -0,0 +1,42 @@
+.. _installation:
+
+Installation
+============
+
+Quick Installation
+------------------
+
+The quick way to install The Littlest JupyterHub (tljh) is:
+
+.. code-block:: bash
+
+   curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/installer/install.bash | sudo bash -
+
+This takes 2-5 minutes to run. When completed, you can access your new JupyterHub
+at the public IP of your server!
+
+You should probably add yourself as an `admin user <admin.md>`_
+after installation.
+
+Slightly less quick installation
+--------------------------------
+
+If you can read ``bash`` and are nervous about the previous installation method,
+you can inspect the installer script before running it.
+
+
+1. Download the installer script
+
+   .. code-block:: bash
+
+      curl https://raw.githubusercontent.com/yuvipanda/the-littlest-jupyterhub/master/installer/install.bash  -o install.bash
+
+2. Read the install script source using your favorite text editor
+
+3. Run the installer script
+
+   .. code-block:: bash
+
+      sudo install.bash
+
+   This should have the exact same effects as the quick installer method.

docs/requirements.rst

@@ -1,11 +1,15 @@
-# Server Requirements
+.. _requirements:
+
+Server Requirements
+===================
 
 The Littlest JupyterHub (TLJH) can run on servers that meet at least he following criteria:
 
-1. Ubuntu Linux Operating System (minimum version supported 18.04)
+
-2. Full root access
+#. Ubuntu Linux Operating System (minimum version supported 18.04)
-3. Access to the internet
+#. Full root access
-4. At least 512MB of RAM
+#. Access to the internet
+#. At least 512MB of RAM
 
 While TLJH will run on machines that meet these requirements, you should also
 consider how much resources your individual users need before acquiring a server.

mkdocs.yml

@@ -1,2 +0,0 @@
-site_name: The Littlest JupyterHub
-theme: readthedocs