Merge pull request #299 from datalayer-contrib/docs-1.0.0-review

docs: reviews for release 1.0.0
jupyter-server · Sep 18, 2020 · a7bf2e8 · a7bf2e8
2 parents 097676b + 36d259b
commit a7bf2e8
Show file tree

Hide file tree

Showing 10 changed files with 224 additions and 14 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,3 @@
+# Jupyter Server Docs Sources
+
+Read [this page](https://jupyter-server.readthedocs.io/en/latest/contributors/contributing.html#building-the-docs) to build the docs.
diff --git a/docs/source/developers/dependency.rst b/docs/source/developers/dependency.rst
@@ -18,4 +18,4 @@ To pin your jupyter_server install to a specific version:
 
 .. code-block:: console
 
-    > pip install jupyter_server==1.0
+    > pip install jupyter_server==1.0.0
diff --git a/docs/source/developers/extensions.rst b/docs/source/developers/extensions.rst
@@ -4,6 +4,9 @@ Server Extensions
 
 A Jupyter Server extension is typically a module or package that extends to Server’s REST API/endpoints—i.e. adds extra request handlers to Server’s Tornado Web Application.
 
+You can check some simple examples on the `examples folder
+<https://github.com/jupyter/jupyter_server/tree/master/examples/simple>`_ in the GitHub jupyter_server repository.
+
 Authoring a basic server extension
 ==================================
 
@@ -376,12 +379,6 @@ Putting it all together, authors can distribute their extension following this s
         )
 
 
-Example Server Extension
-========================
-
-You can check some simple example on the `GitHub jupyter_server repository
-<https://github.com/jupyter/jupyter_server/tree/master/examples/simple>`_.
-
 
 
 .. links

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -3,9 +3,9 @@ Welcome!
 
 You've landed on the documentation pages for the **Jupyter Server** Project. Some other pages you may have been looking for:
 
-* `Jupyter Server Github Repo <https://github.com/jupyter/jupyter_server>`_
-* `JupyterLab Github Repo <https://github.com/jupyterlab/jupyterlab>`_
-* `Jupyter Notebook Github Repo <https://github.com/jupyter/notebook>`_
+* `Jupyter Server Github Repo <https://github.com/jupyter/jupyter_server>`_, the source code we describe in this code.
+* `Jupyter Notebook Github Repo <https://github.com/jupyter/notebook>`_ , the source code for the classic Notebook.
+* `JupyterLab Github Repo <https://github.com/jupyterlab/jupyterlab>`_, the JupyterLab server wich runs on the Jupyter Server.
 
 
 Introduction
@@ -15,7 +15,7 @@ Jupyter Server is the backend—the core services, APIs, and `REST endpoints`_
 
 .. note::
 
-   Jupyter Server is a replacement for the Tornado Web Server in `Jupyter Notebook`_. Jupyter web applications should move to using Jupyter Server. For help, see `this page <operators/migrate-from-nbserver>`_.
+   Jupyter Server is a replacement for the Tornado Web Server in `Jupyter Notebook`_. Jupyter web applications should move to using Jupyter Server. For help, see the :ref:`migrate_from_notebook` page.
 
 .. _Tornado: https://www.tornadoweb.org/en/stable/
 .. _Jupyter Notebook: https://github.com/jupyter/notebook

diff --git a/docs/source/operators/ipython_security.asc b/docs/source/operators/ipython_security.asc
@@ -0,0 +1,52 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG v2.0.22 (GNU/Linux)
+
+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
+5vmLc+Ibz+eT+rM=
+=XVDe
+-----END PGP PUBLIC KEY BLOCK-----
diff --git a/docs/source/operators/migrate-from-nbserver.rst b/docs/source/operators/migrate-from-nbserver.rst
@@ -29,7 +29,7 @@ You will have to create the following ``jupyter_server_config.py`` file.
 Running Jupyter Notebook on Jupyter Server
 ==========================================
 
-If you want to switch to Jupyter Server, but you still want to serve `Jupyter Notebook <https://github.com/jupyter/notebook>`_ to users, you can try `NBClassic <https://github.com/Zsailer/nbclassic>`_.
+If you want to switch to Jupyter Server, but you still want to serve `Jupyter Notebook <https://github.com/jupyter/notebook>`_ to users, you can try `NBClassic <https://github.com/jupyterlab/nbclassic>`_.
 
 NBClassic is a Jupyter Server extension that serves the Notebook frontend (i.e. all static assets) on top of Jupyter Server. It even loads Jupyter Notebook's config files.
 

diff --git a/docs/source/operators/security.rst b/docs/source/operators/security.rst
@@ -77,3 +77,144 @@ but this is **NOT RECOMMENDED**, unless authentication or access restrictions ar
     c.ServerApp.token = ''
     c.ServerApp.password = ''
 
+Security in notebook documents
+==============================
+
+As Jupyter Server become more popular for sharing and collaboration,
+the potential for malicious people to attempt to exploit the notebook
+for their nefarious purposes increases. IPython 2.0 introduced a
+security model to prevent execution of untrusted code without explicit
+user input.
+
+The problem
+-----------
+
+The whole point of Jupyter is arbitrary code execution. We have no
+desire to limit what can be done with a notebook, which would negatively
+impact its utility.
+
+Unlike other programs, a Jupyter notebook document includes output.
+Unlike other documents, that output exists in a context that can execute
+code (via Javascript).
+
+The security problem we need to solve is that no code should execute
+just because a user has **opened** a notebook that **they did not
+write**. Like any other program, once a user decides to execute code in
+a notebook, it is considered trusted, and should be allowed to do
+anything.
+
+Our security model
+------------------
+
+-  Untrusted HTML is always sanitized
+-  Untrusted Javascript is never executed
+-  HTML and Javascript in Markdown cells are never trusted
+-  **Outputs** generated by the user are trusted
+-  Any other HTML or Javascript (in Markdown cells, output generated by
+   others) is never trusted
+-  The central question of trust is "Did the current user do this?"
+
+The details of trust
+--------------------
+
+When a notebook is executed and saved, a signature is computed from a
+digest of the notebook's contents plus a secret key. This is stored in a
+database, writable only by the current user. By default, this is located at::
+
+    ~/.local/share/jupyter/nbsignatures.db  # Linux
+    ~/Library/Jupyter/nbsignatures.db       # OS X
+    %APPDATA%/jupyter/nbsignatures.db       # Windows
+
+Each signature represents a series of outputs which were produced by code the
+current user executed, and are therefore trusted.
+
+When you open a notebook, the server computes its signature, and checks if it's
+in the database. If a match is found, HTML and Javascript
+output in the notebook will be trusted at load, otherwise it will be
+untrusted.
+
+Any output generated during an interactive session is trusted.
+
+Updating trust
+**************
+
+A notebook's trust is updated when the notebook is saved. If there are
+any untrusted outputs still in the notebook, the notebook will not be
+trusted, and no signature will be stored. If all untrusted outputs have
+been removed (either via ``Clear Output`` or re-execution), then the
+notebook will become trusted.
+
+While trust is updated per output, this is only for the duration of a
+single session. A newly loaded notebook file is either trusted or not in its
+entirety.
+
+Explicit trust
+**************
+
+Sometimes re-executing a notebook to generate trusted output is not an
+option, either because dependencies are unavailable, or it would take a
+long time. Users can explicitly trust a notebook in two ways:
+
+-  At the command-line, with::
+
+    jupyter trust /path/to/notebook.ipynb
+
+-  After loading the untrusted notebook, with ``File / Trust Notebook``
+
+These two methods simply load the notebook, compute a new signature, and add
+that signature to the user's database.
+
+Reporting security issues
+-------------------------
+
+If you find a security vulnerability in Jupyter, either a failure of the
+code to properly implement the model described here, or a failure of the
+model itself, please report it to [email protected].
+
+If you prefer to encrypt your security reports,
+you can use :download:`this PGP public key <ipython_security.asc>`.
+
+Affected use cases
+------------------
+
+Some use cases that work in Jupyter 1.0 became less convenient in
+2.0 as a result of the security changes. We do our best to minimize
+these annoyances, but security is always at odds with convenience.
+
+Javascript and CSS in Markdown cells
+************************************
+
+While never officially supported, it had become common practice to put
+hidden Javascript or CSS styling in Markdown cells, so that they would
+not be visible on the page. Since Markdown cells are now sanitized (by
+`Google Caja <https://developers.google.com/caja>`__), all Javascript
+(including click event handlers, etc.) and CSS will be stripped.
+
+We plan to provide a mechanism for notebook themes, but in the meantime
+styling the notebook can only be done via either ``custom.css`` or CSS
+in HTML output. The latter only have an effect if the notebook is
+trusted, because otherwise the output will be sanitized just like
+Markdown.
+
+Collaboration
+*************
+
+When collaborating on a notebook, people probably want to see the
+outputs produced by their colleagues' most recent executions. Since each
+collaborator's key will differ, this will result in each share starting
+in an untrusted state. There are three basic approaches to this:
+
+-  re-run notebooks when you get them (not always viable)
+-  explicitly trust notebooks via ``jupyter trust`` or the notebook menu
+   (annoying, but easy)
+-  share a notebook signatures database, and use configuration dedicated to the
+   collaboration while working on the project.
+
+To share a signatures database among users, you can configure:
+
+.. code-block:: python
+
+    c.NotebookNotary.data_dir = "/path/to/signature_dir"
+
+to specify a non-default path to the SQLite database (of notebook hashes,
+essentially).
diff --git a/docs/source/other/changelog.rst b/docs/source/other/changelog.rst
@@ -21,6 +21,17 @@ We strongly recommend that you upgrade to version 9+ of pip before upgrading ``j
     Use ``pip install pip --upgrade`` to upgrade pip. Check pip version with
     ``pip --version``.
 
+.. _release-1.0.0:
+
+1.0.0
+-----
+
+- Extension discovery
+- Classic server extension discovery and support
+- Bug fixes
+- Ready for users
+- JupyterLab is the first server running on top of Jupyter Server
+
 .. _release-0.0.2:
 
 0.0.2

diff --git a/docs/source/other/full-config.rst b/docs/source/other/full-config.rst
@@ -669,7 +669,7 @@ Session.unpacker : DottedObjectName
     Only used with custom functions for `packer`.
 
 Session.username : Unicode
-    Default: ``'zsailer'``
+    Default: ``'echar4'``
 
     Username for the Session. Default is your system username.
 
@@ -685,6 +685,11 @@ MultiKernelManager.kernel_manager_class : DottedObjectName
     subclassing of the KernelManager for customized behavior.
 
 
+MultiKernelManager.shared_context : Bool
+    Default: ``True``
+
+    Share a single zmq.Context to talk to all my kernels
+
 MappingKernelManager.allowed_message_types : List
     Default: ``[]``
 
@@ -897,7 +902,7 @@ FileContentsManager.root_dir : Unicode
 
     No description
 
-NotebookNotary.algorithm : 'md5'|'sha3_384'|'sha3_512'|'sha256'|'sha1'|'blake2s'|'sha3_256'|'sha3_224'|'sha384'|'sha512'|'blake2b'|'sha224'
+NotebookNotary.algorithm : 'md5'|'sha3_512'|'blake2b'|'sha3_384'|'sha3_256'|'sha224'|'sha3_224'|'sha384'|'sha512'|'blake2s'|'sha1'|'sha256'
     Default: ``'sha256'``
 
     The hashing algorithm used to sign notebooks.

diff --git a/docs/source/users/index.rst b/docs/source/users/index.rst
@@ -5,6 +5,7 @@ The Jupyter Server is a highly technical piece of the Jupyter Stack, so users pr
 
 
 .. toctree::
+   :caption: Users
    :maxdepth: 1
    :name: users
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Jupyter Server Docs Sources

		Read [this page](https://jupyter-server.readthedocs.io/en/latest/contributors/contributing.html#building-the-docs) to build the docs.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -18,4 +18,4 @@ To pin your jupyter_server install to a specific version:

		.. code-block:: console

		> pip install jupyter_server==1.0
		> pip install jupyter_server==1.0.0