From aa01225b0a01f27149d5d161716851ada257cdb9 Mon Sep 17 00:00:00 2001 From: yuvipanda Date: Thu, 28 Jun 2018 00:39:55 -0700 Subject: [PATCH] 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 | 20 ++++++++++ docs/{admin.md => admin.rst} | 43 +++++++++++----------- docs/conf.py | 32 ++++++++++++++++ docs/index.md | 24 ------------ docs/index.rst | 27 ++++++++++++++ docs/install.rst | 42 +++++++++++++++++++++ docs/{requirements.md => requirements.rst} | 14 ++++--- mkdocs.yml | 2 - 8 files changed, 152 insertions(+), 52 deletions(-) create mode 100644 docs/Makefile rename docs/{admin.md => admin.rst} (56%) create mode 100644 docs/conf.py delete mode 100644 docs/index.md create mode 100644 docs/index.rst create mode 100644 docs/install.rst rename docs/{requirements.md => requirements.rst} (56%) delete mode 100644 mkdocs.yml diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..7d07064 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/admin.md b/docs/admin.rst similarity index 56% rename from docs/admin.md rename to docs/admin.rst index 6f94dc0..5841b8e 100644 --- a/docs/admin.md +++ b/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 -and more! +4. Change amount of RAM / CPU available to each user 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) -config file at `/opt/tljh/config.yaml`. +Admin users are specified in the `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 - sudo nano /opt/tljh/config.yaml - ``` + .. code-block:: bash + + sudo nano /opt/tljh/config.yaml 2. Add usernames that should have admin access. - ```yaml - users: - admin: - - user1 - - user2 - ``` + .. code-block:: yaml + + users: + admin: + - 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 - sudo systemctl restart jupyterhub - ``` + .. code-block:: bash + + 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 -2. Opening your JupyterHub `Control Panel` and checking for the **Admin** tab +1. Opening a Terminal in your JupyterHub and checking if ``sudo`` works +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. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..cd856fc --- /dev/null +++ b/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'] diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index c85e4bb..0000000 --- a/docs/index.md +++ /dev/null @@ -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 | 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) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..6949388 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,27 @@ +The Littlest JupyterHub +----------------------- + +A simple `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 | sudo bash -``) +makes you nervous, check out the :ref:`other installation methods ` we support! + +.. toctree:: + :maxdepth: 1 + + requirements + install + admin diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..67d4a20 --- /dev/null +++ b/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 `_ +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. diff --git a/docs/requirements.md b/docs/requirements.rst similarity index 56% rename from docs/requirements.md rename to docs/requirements.rst index 875dece..3028064 100644 --- a/docs/requirements.md +++ b/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 -3. Access to the internet -4. At least 512MB of RAM + +#. Ubuntu Linux Operating System (minimum version supported 18.04) +#. Full root access +#. 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. diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index c57dd75..0000000 --- a/mkdocs.yml +++ /dev/null @@ -1,2 +0,0 @@ -site_name: The Littlest JupyterHub -theme: readthedocs