diff --git a/.circleci/config.yml b/.circleci/config.yml index 1a6c4db..038a112 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -101,9 +101,53 @@ jobs: command: | python3 .circleci/integration-test.py run 'python3 -m pytest -v /srv/src/integration-tests' + documentation: + docker: + # Match target OS of TLJH + - image: ubuntu:18.04 + + working_directory: ~/repo + + steps: + - checkout + + # Setup Python + - run: + name: install python + command: | + apt-get update --yes && apt-get install --yes python3 python3-venv git make + + # Download and cache dependencies + - restore_cache: + key: v1-dependencies-py3.6-sphinx + + - run: + name: Setup venv + command: | + python3 -m venv /srv/venv + echo 'export PATH=/srv/venv/bin:$PATH' >> $BASH_ENV + + - run: + name: install dependencies + command: | + pip install sphinx + pip install -r docs/doc-requirements.txt + + - save_cache: + paths: + - /srv/venv/ + key: v1-dependencies-py3.6-sphinx + + - run: + name: build documentation + command: | + cd docs + make html + workflows: version: 2 all-tests: jobs: - unit-test - integration-test + - documentation diff --git a/docs/Makefile b/docs/Makefile index 7d07064..5b24fa0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W SPHINXBUILD = sphinx-build SPHINXPROJ = TheLittlestJupyterHub SOURCEDIR = . @@ -17,4 +17,4 @@ help: # 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 + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py index 327e27e..dc1e899 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,9 @@ def setup(app): app.add_javascript("https://cdn.jsdelivr.net/npm/clipboard@1/dist/clipboard.min.js") # Enable MathJax for Math -extensions = ['sphinx.ext.mathjax', 'sphinx_copybutton.sphinx_copybutton'] +extensions = ['sphinx.ext.mathjax', + 'sphinx.ext.intersphinx', + 'sphinx_copybutton.sphinx_copybutton'] # The master toctree document. master_doc = 'index' @@ -25,7 +27,14 @@ 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'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', + 'install/custom.rst'] + +intersphinx_mapping = { + 'sphinx': ('http://www.sphinx-doc.org/en/master/', None), +} + +intersphinx_cache_limit = 90 # days # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/docs/contributing/docs.rst b/docs/contributing/docs.rst index ee2bbbf..fb0adbb 100644 --- a/docs/contributing/docs.rst +++ b/docs/contributing/docs.rst @@ -50,18 +50,18 @@ __ http://docutils.sourceforge.net/ To build the documentation locally, install Sphinx: -.. console:: +.. code-block:: console $ pip install Sphinx Then from the ``docs`` directory, build the HTML: -.. console:: +.. code-block:: console $ make html To get started contributing, you'll want to read the :ref:`reStructuredText -reference `. +reference ` Your locally-built documentation will be themed differently than the documentation at `the-littlest-jupyterhub.readthedocs.io `_. diff --git a/docs/howto/user-environment.rst b/docs/howto/user-environment.rst index c0a25ed..a206c4e 100644 --- a/docs/howto/user-environment.rst +++ b/docs/howto/user-environment.rst @@ -6,7 +6,7 @@ Install conda, pip or apt packages :abbr:`TLJH (The Littlest JupyterHub)` starts all users in the same `conda `_ environment. Packages / libraries installed in this environment are available -to all users on the JupyterHub. Users with :ref:`admin_access` can install packages +to all users on the JupyterHub. Users with :ref:`admin rights ` can install packages easily. .. _user_environment_pip: diff --git a/docs/index.rst b/docs/index.rst index 52bf9aa..96c6590 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,10 +30,7 @@ Ubuntu 18.04. We have a bunch of tutorials to get you started. install/digitalocean install/jetstream install/google - -- :ref:`install/custom`. - You should use this if your cloud provider does not already have a direct tutorial, - or if you have experience setting up servers. + install/custom-server Once you are ready to run your server for real, it's a good idea to proceed directly to :doc:`howto/https`. diff --git a/docs/install/custom.rst b/docs/install/custom-server.rst similarity index 94% rename from docs/install/custom.rst rename to docs/install/custom-server.rst index 645f707..c340827 100644 --- a/docs/install/custom.rst +++ b/docs/install/custom-server.rst @@ -4,6 +4,12 @@ Installing on your own server ============================= +.. note:: + + You should use this if your cloud provider does not already have a direct tutorial, + or if you have experience setting up servers. + + Goal ==== diff --git a/docs/topic/authenticator-configuration.rst b/docs/topic/authenticator-configuration.rst index af50c0a..0341761 100644 --- a/docs/topic/authenticator-configuration.rst +++ b/docs/topic/authenticator-configuration.rst @@ -27,7 +27,7 @@ Setting authenticator properties JupyterHub authenticators are customized by setting *traitlet properties*. In the authenticator's documentation, you will find these are usually represented as: -.. code-block:: +.. code-block:: python c.. = @@ -40,7 +40,7 @@ You can set these with ``tljh-config`` with: Example ------- -LDAPAuthenticator's `documentation `_ +`LDAPAuthenticator's documentation `_ lists the various configuration options you can set for LDAPAuthenticator. When the documentation asks you to set ``LDAPAuthenticator.server_address`` to some value, you can do that with the following command: diff --git a/docs/topic/security.rst b/docs/topic/security.rst index b59d911..b4d8d8f 100644 --- a/docs/topic/security.rst +++ b/docs/topic/security.rst @@ -50,7 +50,8 @@ even after you remove them from JupyterHub. Admins should manually remove the us from the server & archive their home directories as needed. For example, the following command deletes the unix user associated with the JupyterHub user ``yuvipanda``. -.. code-block:: +.. code-block:: bash + sudo userdel jupyter-yuvipanda If the user removed from the server is an admin, extra care must be taken @@ -69,4 +70,4 @@ HTTPS ===== Any internet-facing JupyterHub should use HTTPS to secure its traffic. For -information on how to use HTTPS with your JupyterHub, see :ref:`_howto/https`. +information on how to use HTTPS with your JupyterHub, see :ref:`howto/https`. diff --git a/docs/topic/whentouse.rst b/docs/topic/whentouse.rst index d2b77c8..2f66e2e 100644 --- a/docs/topic/whentouse.rst +++ b/docs/topic/whentouse.rst @@ -9,12 +9,12 @@ This page is a brief guide to determining whether to use The Littlest JupyterHub Many of these ideas were first laid out in a `blog post announcing TLJH `_. -**The Littlest JupyterHub (TLJH)** (`link `_) is an opinionated and pre-configured distribution +`**The Littlest JupyterHub (TLJH)** `_ is an opinionated and pre-configured distribution to deploy a JupyterHub on a **single machine** (in the cloud or on your own hardware). It is designed to be a more lightweight and maintainable solution for use-cases where size, scalability, and cost-savings are not a huge concern. -**Zero to JupyterHub on Kubernetes** (`link `_) allows you +`**Zero to JupyterHub on Kubernetes** `_ allows you to deploy JupyterHub on **Kubernetes**. This allows JupyterHub to scale to many thousands of users, to flexibly grow/shrink the size of resources it needs, and to use container technology in administering user sessions.