Merge pull request #107 from betatim/jlab-docs

[MRG] Adding CI for documentation and fixing docs warnings

.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

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)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

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'

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 <sphinx:rst-index>`.
+reference <sphinx:rst-index>`
 
 Your locally-built documentation will be themed differently than the
 documentation at `the-littlest-jupyterhub.readthedocs.io <https://the-littlest-jupyterhub.readthedocs.io>`_.

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 <https://conda.io/docs/>`_
 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 <howto/admin-users>` can install packages
 easily.
 
 .. _user_environment_pip:

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
-
+     install/custom-server
-- :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.
 
 Once you are ready to run your server for real,
 it's a good idea to proceed directly to :doc:`howto/https`.

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
 ====
 

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.<AuthenticatorName>.<property-name> = <some-value>
 
@@ -40,7 +40,7 @@ You can set these with ``tljh-config`` with:
 Example
 -------
 
-LDAPAuthenticator's `documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
+`LDAPAuthenticator's documentation <https://github.com/jupyterhub/ldapauthenticator#required-configuration>`_
 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:

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`.

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 <http://words.yuvi.in/post/the-littlest-jupyterhub/>`_.
 
-**The Littlest JupyterHub (TLJH)** (`link <https://the-littlest-jupyterhub.readthedocs.io/en/latest/>`_) is an opinionated and pre-configured distribution
+`**The Littlest JupyterHub (TLJH)** <https://the-littlest-jupyterhub.readthedocs.io/en/latest/>`_ 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 <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_) allows you
+`**Zero to JupyterHub on Kubernetes** <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_ 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.