From a45f4199874c24d90bba52f66a9390fd59c1c4f6 Mon Sep 17 00:00:00 2001 From: Zachary Sailer Date: Tue, 21 Apr 2020 14:49:12 -0700 Subject: [PATCH] [WIP] Major revamp of documentation (#196) * Docs WIP * add user docs * start operator docs * [wip] more docs * rearrage some developer docs * more docs * update readme * switch to pydata theme * minor changes to docs * update extending docs * update docs * minor typo --- CONTRIBUTING.rst | 26 +- README.md | 44 +- docs/autogen_config.py | 12 +- docs/doc-requirements.txt | 4 +- docs/environment.yml | 2 + docs/source/_static/jupyter_server_logo.svg | 191 +++ docs/source/conf.py | 32 +- docs/source/config_overview.rst | 64 - docs/source/contributing.rst | 3 - docs/source/contributors/contributing.rst | 3 + docs/source/contributors/index.rst | 12 + docs/source/contributors/team-meetings.rst | 21 + .../{extending => developers}/contents.rst | 0 docs/source/developers/dependency.rst | 21 + docs/source/developers/extensions.rst | 378 ++++++ docs/source/developers/index.rst | 16 + docs/source/developers/rest-api.rst | 4 + .../{extending => developers}/savehooks.rst | 0 docs/source/extending/bundler_extensions.rst | 182 --- docs/source/extending/handlers.rst | 127 -- docs/source/extending/index.rst | 15 - docs/source/frontends.rst | 144 --- docs/source/index.rst | 59 +- docs/source/migrate_from_notebook.rst | 26 - .../operators/configuring-extensions.rst | 59 + docs/source/operators/index.rst | 15 + .../operators/migrate-from-nbserver.rst | 36 + docs/source/operators/multiple-extensions.rst | 89 ++ .../public-server.rst} | 27 +- docs/source/{ => operators}/security.rst | 0 docs/source/{ => other}/changelog.rst | 0 docs/source/other/faq.rst | 14 + docs/source/other/full-config.rst | 1031 +++++++++++++++++ docs/source/other/index.rst | 10 + docs/source/other/links.rst | 9 + docs/source/users/configuration.rst | 68 ++ docs/source/users/help.rst | 8 + docs/source/users/index.rst | 14 + docs/source/users/installation.rst | 22 + docs/source/users/launching.rst | 26 + 40 files changed, 2135 insertions(+), 679 deletions(-) create mode 100644 docs/source/_static/jupyter_server_logo.svg delete mode 100644 docs/source/config_overview.rst delete mode 100644 docs/source/contributing.rst create mode 100644 docs/source/contributors/contributing.rst create mode 100644 docs/source/contributors/index.rst create mode 100644 docs/source/contributors/team-meetings.rst rename docs/source/{extending => developers}/contents.rst (100%) create mode 100644 docs/source/developers/dependency.rst create mode 100644 docs/source/developers/extensions.rst create mode 100644 docs/source/developers/index.rst create mode 100644 docs/source/developers/rest-api.rst rename docs/source/{extending => developers}/savehooks.rst (100%) delete mode 100644 docs/source/extending/bundler_extensions.rst delete mode 100644 docs/source/extending/handlers.rst delete mode 100644 docs/source/extending/index.rst delete mode 100644 docs/source/frontends.rst delete mode 100644 docs/source/migrate_from_notebook.rst create mode 100644 docs/source/operators/configuring-extensions.rst create mode 100644 docs/source/operators/index.rst create mode 100644 docs/source/operators/migrate-from-nbserver.rst create mode 100644 docs/source/operators/multiple-extensions.rst rename docs/source/{public_server.rst => operators/public-server.rst} (96%) rename docs/source/{ => operators}/security.rst (100%) rename docs/source/{ => other}/changelog.rst (100%) create mode 100644 docs/source/other/faq.rst create mode 100644 docs/source/other/full-config.rst create mode 100644 docs/source/other/index.rst create mode 100644 docs/source/other/links.rst create mode 100644 docs/source/users/configuration.rst create mode 100644 docs/source/users/help.rst create mode 100644 docs/source/users/index.rst create mode 100644 docs/source/users/installation.rst create mode 100644 docs/source/users/launching.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a23cbbf4ec..2d40de2b51 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,5 +1,5 @@ -Contributing to the Jupyter Server -================================== +General Jupyter contributor guidelines +====================================== If you're reading this section, you're probably interested in contributing to Jupyter. Welcome and thanks for your interest in contributing! @@ -8,19 +8,16 @@ Please take a look at the Contributor documentation, familiarize yourself with using the Jupyter Server, and introduce yourself on the mailing list and share what area of the project you are interested in working on. -General Guidelines ------------------- - For general documentation about contributing to Jupyter projects, see the `Project Jupyter Contributor Documentation`__. __ https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html Setting Up a Development Environment ------------------------------------- +==================================== Installing the Jupyter Server -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------- Once you have installed the dependencies mentioned above, use the following steps:: @@ -39,7 +36,7 @@ from any directory in your system with:: jupyter server Troubleshooting the Installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------------- If you do not see that your Jupyter Server is not running on dev mode, it's possible that you are running other instances of Jupyter Server. You can try the following steps: @@ -54,10 +51,7 @@ running other instances of Jupyter Server. You can try the following steps: 5. Verify the installation with the steps in the previous section. Running Tests -------------- - -Python Tests -^^^^^^^^^^^^ +============= Install dependencies:: @@ -67,12 +61,8 @@ To run the Python tests, use:: pytest -If you want coverage statistics as well, you can run:: - - py.test --cov notebook -v - -Building the Documentation --------------------------- +Building the Docs +================= To build the documentation you'll need `Sphinx `_, `pandoc `_ and a few other packages. diff --git a/README.md b/README.md index 9b42800459..32482501f0 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,13 @@ # Jupyter Server -[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter) [![Build Status](https://github.com/jupyter/jupyter_server/workflows/CI/badge.svg)](https://github.com/jupyter/jupyter_server/actions) [![Documentation Status](https://readthedocs.org/projects/jupyter-server/badge/?version=latest)](http://jupyter-server.readthedocs.io/en/latest/?badge=latest) -The Jupyter Server provides the backend for Jupyter web applications such as -the Jupyter notebook and JupyterLab. +The Jupyter Server provides the backend (i.e. the core services, APIs, and REST endpoints) for Jupyter web applications like Jupyter notebook, JupyterLab, and Voila. -**jupyter_server is an early developer preview, and is not suitable for general -usage yet. Features and implementation are subject to change. Please use the -stable [notebook server](https://github.com/jupyter/notebook) for production -usecases.** +For more information, read our [documentation here](http://jupyter-server.readthedocs.io/en/latest/?badge=latest). -Read more on the Jupyter Server [roadmap](https://github.com/jupyter/jupyter_server/issues/127). - -## Installation - -You can find the installation documentation for the -[Jupyter platform, on ReadTheDocs](https://jupyter.readthedocs.io/en/latest/install.html). -The documentation for advanced usage of Jupyter notebook can be found -[here](https://jupyter-server.readthedocs.io/en/latest/). +## Installation and Basic usage To install the latest release locally, make sure you have [pip installed](https://pip.readthedocs.io/en/stable/installing/) and run: @@ -54,34 +42,18 @@ Launch with: $ jupyter server -### Running in a remote installation - -You need some configuration before starting Jupyter server remotely. See [Running a Jupyter server](http://jupyter-server.readthedocs.io/en/stable/public_server.html). - -## Development Installation - -See [`CONTRIBUTING.rst`](CONTRIBUTING.rst) for how to set up a local development installation. - ## Contributing If you are interested in contributing to the project, see [`CONTRIBUTING.rst`](CONTRIBUTING.rst). -## Weekly Dev Meeting - -We have videoconference meetings every week where we discuss what we have been working on and get feedback from one another. - -Anyone is welcome to attend, if they would like to discuss a topic or just to listen in. +## Team Meetings and Roadmap When: Thursdays [8:00am, Pacific time](https://www.thetimezoneconverter.com/?t=8%3A00%20am&tz=San%20Francisco&) Where: [calpoly/jupyter Zoom](https://zoom.us/my/jovyan) What: [Meeting notes](https://github.com/jupyter/jupyter_server/issues/126) -## Resources +* When: Thursdays [8:00am, Pacific time](https://www.thetimezoneconverter.com/?t=8%3A00%20am&tz=San%20Francisco&) +* Where: [Jupyter Zoom](https://calpoly.zoom.us/my/jupyter) +* What: [Meeting notes](https://github.com/jupyter/jupyter_server/issues/126) -- [Project Jupyter website](https://jupyter.org) -- [Online Demo at try.jupyter.org](https://try.jupyter.org) -- [Documentation for Jupyter Server](https://jupyter-server.readthedocs.io/en/latest/) [[PDF](https://media.readthedocs.org/pdf/jupyter-server/latest/jupyter-server.pdf)] -- [Korean Version of Installation](https://github.com/ChungJooHo/Jupyter_Kor_doc/) -- [Documentation for Project Jupyter](https://jupyter.readthedocs.io/en/latest/index.html) [[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)] -- [Issues](https://github.com/jupyter/jupyter-server/issues) -- [Technical support - Jupyter Google Group](https://groups.google.com/forum/#!forum/jupyter) +See our tentative [roadmap here](https://github.com/jupyter/jupyter_server/issues/127). diff --git a/docs/autogen_config.py b/docs/autogen_config.py index c70aacc7f7..37ee1875da 100644 --- a/docs/autogen_config.py +++ b/docs/autogen_config.py @@ -4,14 +4,14 @@ from jupyter_server.serverapp import ServerApp header = """\ -.. _config: +.. _other-full-config: Config file and command line options ==================================== The Jupyter Server can be run with a variety of command line arguments. -A list of available options can be found below in the :ref:`options section +A list of available options can be found below in the :ref:`options section `. Defaults for these options can also be set by creating a file named @@ -29,16 +29,16 @@ Options ------- -This list of options can be generated by running the following and hitting +This list of options can be generated by running the following and hitting enter:: - $ jupyter server --help + $ jupyter server --help-all """ try: - destination = os.path.join(os.path.dirname(__file__), 'source/config.rst') + destination = os.path.join(os.path.dirname(__file__), 'source/other/full-config.rst') except: - destination = os.path.join(os.getcwd(), 'config.rst') + destination = os.path.join(os.getcwd(), 'full-config.rst') with open(destination, 'w') as f: f.write(header) diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt index a99918f253..7e4bfc51a6 100644 --- a/docs/doc-requirements.txt +++ b/docs/doc-requirements.txt @@ -1,3 +1,5 @@ sphinx>=1.3.6 -sphinx-rtd-theme +git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master sphinxcontrib_github_alt +sphinxcontrib-openapi +sphinxemoji \ No newline at end of file diff --git a/docs/environment.yml b/docs/environment.yml index 23f013f6be..4fddbd678b 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -12,3 +12,5 @@ dependencies: - Send2Trash - prometheus_client - sphinxcontrib_github_alt + - sphinxcontrib-openapi + - sphinxemoji \ No newline at end of file diff --git a/docs/source/_static/jupyter_server_logo.svg b/docs/source/_static/jupyter_server_logo.svg new file mode 100644 index 0000000000..586c16b0b9 --- /dev/null +++ b/docs/source/_static/jupyter_server_logo.svg @@ -0,0 +1,191 @@ + + + + + + image/svg+xml + + logo.svg + + + + logo.svg + Created using Figma 0.90 + + + + + + + + + + + + + + + + + + + + + + + + + + + server + diff --git a/docs/source/conf.py b/docs/source/conf.py index d0f5478647..e105e82d40 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -70,6 +70,8 @@ 'sphinx.ext.mathjax', 'IPython.sphinxext.ipython_console_highlighting', 'sphinxcontrib_github_alt', + 'sphinxcontrib.openapi', + 'sphinxemoji.sphinxemoji' ] # Add any paths that contain templates here, relative to this directory. @@ -88,7 +90,7 @@ # General information about the project. project = 'Jupyter Server' -copyright = '2015, Jupyter Team, https://jupyter.org' +copyright = '2020, Jupyter Team, https://jupyter.org' author = 'The Jupyter Team' # ghissue config @@ -151,26 +153,28 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False -# Add custom note for each doc page +# # Add custom note for each doc page -rst_prolog = "" +# rst_prolog = "" -rst_prolog += """ -.. important:: - This documentation covers Jupyter Server, an **early developer preview**, - and is not suitable for general usage yet. Features and implementation are - subject to change. +# rst_prolog += """ +# .. important:: +# This documentation covers Jupyter Server, an **early developer preview**, +# and is not suitable for general usage yet. Features and implementation are +# subject to change. - For production use cases, please use the stable notebook server in the - `Jupyter Notebook repo `_ - and `Jupyter Notebook documentation `_. -""" +# For production use cases, please use the stable notebook server in the +# `Jupyter Notebook repo `_ +# and `Jupyter Notebook documentation `_. +# """ # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +#html_theme = 'sphinx_rtd_theme' +html_theme = "pydata_sphinx_theme" +html_logo = "_static/jupyter_server_logo.svg" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -359,7 +363,7 @@ 'ipython': ('https://ipython.readthedocs.io/en/stable/', None), 'nbconvert': ('https://nbconvert.readthedocs.io/en/latest/', None), 'nbformat': ('https://nbformat.readthedocs.io/en/latest/', None), - 'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None), + 'jupyter': ('https://jupyter.readthedocs.io/en/latest/', None) } spelling_lang='en_US' diff --git a/docs/source/config_overview.rst b/docs/source/config_overview.rst deleted file mode 100644 index ee49b766cd..0000000000 --- a/docs/source/config_overview.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _configuration-overview: - -Configuration Overview -====================== - -Beyond the default configuration settings, you can configure a rich array of -options to suit your workflow. Here are areas that are commonly configured -when using Jupyter Server: - - - :ref:`Jupyter's common configuration system ` - - :ref:`Jupyter server ` - - :ref:`Server extensions ` - -Let's look at highlights of each area. - -.. _configure_common: - -Jupyter's Common Configuration system -------------------------------------- - -Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a -common configuration system. The process for creating a configuration file -and editing settings is similar for all the Jupyter applications. - - - `Jupyter’s Common Configuration Approach `_ - - `Common Directories and File Locations `_ - - `Language kernels `_ - - `traitlets `_ - provide a low-level architecture for configuration. - -.. _configure_server: - -Server-specific configuration ------------------------------ - -The Jupyter server runs the language kernel and communicates with Jupyter Server frontends. - - - Configuring the Jupyter server - - To create a ``jupyter_server_config.py`` file in the ``.jupyter`` - directory, with all the defaults commented out, use the following - command:: - - $ jupyter server --generate-config - - :ref:`Command line arguments for configuration ` settings are - documented in the configuration file and the user documentation. - - - :ref:`Running a Jupyter server ` - - Related: `Configuring a language kernel `_ - to run in the Jupyter server enables your server to run other languages, like R or Julia. - -.. _configure_extensions: - -Server extensions ------------------ - -- `Extending the Server `_ - -Since security -policies vary from organization to organization, we encourage you to -consult with your security team on settings that would be best for your use -cases. Our documentation offers some responsible security practices, and we -recommend becoming familiar with the practices. diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst deleted file mode 100644 index 0f53aeaab6..0000000000 --- a/docs/source/contributing.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. highlight:: sh - -.. include:: ../../CONTRIBUTING.rst diff --git a/docs/source/contributors/contributing.rst b/docs/source/contributors/contributing.rst new file mode 100644 index 0000000000..f7bef4b919 --- /dev/null +++ b/docs/source/contributors/contributing.rst @@ -0,0 +1,3 @@ +.. highlight:: sh + +.. include:: ../../../CONTRIBUTING.rst diff --git a/docs/source/contributors/index.rst b/docs/source/contributors/index.rst new file mode 100644 index 0000000000..0007656dac --- /dev/null +++ b/docs/source/contributors/index.rst @@ -0,0 +1,12 @@ +Documentation for Contributors +------------------------------ + +These pages target people who are interested in contributing directly to the Jupyter Server Project. + +.. toctree:: + :caption: Contributors + :maxdepth: 1 + :name: contributors + + team-meetings + contributing diff --git a/docs/source/contributors/team-meetings.rst b/docs/source/contributors/team-meetings.rst new file mode 100644 index 0000000000..83fa326427 --- /dev/null +++ b/docs/source/contributors/team-meetings.rst @@ -0,0 +1,21 @@ +.. _contributors-team-meetings-roadmap-calendar: + +Team Meetings, Road Map and Calendar +==================================== + +Many of the lead Jupyter Server developers meet weekly over Zoom. These meetings are open to everyone. + +To see when the next meeting is happening, watch this Github issue: + +https://github.com/jupyter/jupyter_server/issues/126 + +Also check out Jupyter Server's roadmap where we track future plans for Jupyter Server: + +https://github.com/jupyter/jupyter_server/issues/127 + + +Jupyter Calendar: + +.. raw:: html + + \ No newline at end of file diff --git a/docs/source/extending/contents.rst b/docs/source/developers/contents.rst similarity index 100% rename from docs/source/extending/contents.rst rename to docs/source/developers/contents.rst diff --git a/docs/source/developers/dependency.rst b/docs/source/developers/dependency.rst new file mode 100644 index 0000000000..a145e4ce8c --- /dev/null +++ b/docs/source/developers/dependency.rst @@ -0,0 +1,21 @@ +Depending on Jupyter Server +=========================== + +If your project depends directly on Jupyter Server, be sure to watch Jupyter Server's :ref:`Change Log ` and pin your project to a version that works for your application. Major releases represent possible backwards-compatibility breaking API changes or features. + +When a new major version in released on PyPI, a branch for that version will be created in this repository, and the version of the master branch will be bumped to the next major version number. That way, the master branch always reflects the latest un-released version. + +To see the changes between releases, checkout the :ref:`Change Log `. + +To install the latest patch of a given version: + +.. code-block:: console + + > pip install jupyter_server --upgrade + + +To pin your jupyter_server install to a specific version: + +.. code-block:: console + + > pip install jupyter_server==1.0 diff --git a/docs/source/developers/extensions.rst b/docs/source/developers/extensions.rst new file mode 100644 index 0000000000..007fba3b64 --- /dev/null +++ b/docs/source/developers/extensions.rst @@ -0,0 +1,378 @@ +================= +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. + +Authoring a basic server extension +================================== + +The simplest way to write a Jupyter Server extension is to write an extension module with a ``_load_jupyter_server_extension`` function. This function should take a single argument, an instance of the ``ServerApp``. + + +.. code-block:: python + + def _load_jupyter_server_extension(serverapp): + """ + This function is called when the extension is loaded. + """ + pass + + +Adding extension endpoints +-------------------------- + +The easiest way to add endpoints and handle incoming requests is to subclass the ``JupyterHandler`` (which itself is a subclass of Tornado's ``RequestHandler``). + +.. code-block:: python + + from jupyter_server.base.handlers import JupyterHandler + + class MyExtensionHandler(JupyterHandler): + + def get(self): + ... + + def post(self): + ... + + +Then add this handler to Jupyter Server's Web Application through the ``_load_jupyter_server_extension`` function. + +.. code-block:: python + + def _load_jupyter_server_extension(serverapp): + """ + This function is called when the extension is loaded. + """ + handlers = [ + ('/myextension/hello', MyExtensionHandler) + ] + serverapp.web_app.add_handlers('.*$', handlers) + + +Making an extension discoverable +-------------------------------- + +To make this extension discoverable to Jupyter Server, first define a ``_jupyter_server_extension_paths()`` function at the root of the module/package. This function returns metadata describing how to load the extension. Usually, this requires a ``module`` key with the import path to the extension's ``_load_jupyter_server_extension`` function. + +.. code-block:: python + + def _jupyter_server_extension_paths(): + """ + Returns a list of dictionaries with metadata describing + where to find the `_load_jupyter_server_extension` function. + """ + return [ + { + "module": "my_extension" + } + ] + +Second, add the extension to the ServerApp's ``jpserver_extensions`` trait. This can be manually added by users in their ``jupyter_server_config.py`` file, + +.. code-block:: python + + c.ServerApp.jpserver_extensions = { + "my_extension": True + } + +or loaded from a JSON file in the ``jupyter_server_config.d`` directory under one of `Jupyter's paths`_. (See the `Distributing a server extension`_ section for details on how to automatically enabled your extension when users install it.) + +.. code-block:: python + + { + "ServerApp": { + "jpserver_extensions": { + "my_extension": true + } + } + } + + +Authoring a configurable extension application +============================================== + +Some extensions are full-fledged client applications that sit on top of the Jupyter Server. For example, `JupyterLab `_ is a server extension. It can be launched from the command line, configured by CLI or config files, and serves+loads static assets behind the server (i.e. html templates, Javascript, etc.) + +Jupyter Server offers a convenient base class, ``ExtensionsApp``, that handles most of the boilerplate code for building such extensions. + +Anatomy of an ``ExtensionApp`` +------------------------------ + +An ExtensionApp: + + - has traits. + - is configurable (from file or CLI) + - has a name (see the ``extension_name`` trait). + - has an entrypoint, ``jupyter ``. + - can serve static content from the ``/static//`` endpoint. + - can add new endpoints to the Jupyter Server. + +The basic structure of an ExtensionApp is shown below: + +.. code-block:: python + + from jupyter_server.extension.application import ExtensionApp + + + class MyExtensionApp(ExtensionApp): + + # -------------- Required traits -------------- + extension_name = "myextension" + extension_url = "/myextension" + load_other_extensions = True + + # --- ExtensionApp traits you can configure --- + static_paths = [...] + template_paths = [...] + settings = {...} + handlers = [...] + + # ----------- add custom traits below --------- + ... + + def initialize_settings(self): + ... + # Update the self.settings trait to pass extra + # settings to the underlying Tornado Web Application. + self.settings.update({'':...}) + + def initialize_handlers(self): + ... + # Extend the self.handlers trait + self.handlers.extend(...) + + def initialize_templates(self): + ... + # Change the jinja templating environment + + +The ``ExtensionApp`` uses the following methods and properties to connect your extension to the Jupyter server. You do no need to define a ``_load_jupyter_server_extension`` function for these apps. Instead, overwrite the pieces below to add your custom settings, handlers and templates: + +Methods + +* ``initialize_setting()``: adds custom settings to the Tornado Web Application. +* ``initialize_handlers()``: appends handlers to the Tornado Web Application. +* ``initialize_templates()``: initialize the templating engine (e.g. jinja2) for your frontend. + +Properties + +* ``extension_name``: the name of the extension +* ``extension_url``: the default url for this extension—i.e. the landing page for this extension when launched from the CLI. +* ``load_other_extensions``: a boolean enabling/disabling other extensions when launching this extension directly. + +``ExtensionApp`` request handlers +--------------------------------- + +``ExtensionApp`` Request Handlers have a few extra properties. + +* ``config``: the ExtensionApp's config object. +* ``server_config``: the ServerApp's config object. +* ``extension_name``: the name of the extension to which this handler is linked. +* ``static_url()``: a method that returns the url to static files (prefixed with ``/static/``). + +Jupyter Server provides a convenient mixin class for adding these properties to any ``JupyterHandler``. For example, the basic server extension handler in the section above becomes: + +.. code-block:: python + + from jupyter_server.base.handlers import JupyterHandler + from jupyter_server.extension.handler import ExtensionHandlerMixin + + + class MyExtensionHandler(ExtensionHandlerMixin, JupyterHandler): + + def get(self): + ... + + def post(self): + ... + + +Jinja templating from frontend extensions +----------------------------------------- + +Many Jupyter frontend applications use Jinja for basic HTML templating. Since this is common enough, Jupyter Server provides some extra mixin that integrate Jinja with Jupyter server extensions. + +Use ``ExtensionAppJinjaMixin`` to automatically add a Jinja templating environment to an ``ExtensionApp``. This adds a ``_jinja2_env`` setting to Tornado Web Server's settings that be be used by request handlers. + +.. code-block:: python + + + from jupyter_server.extension.application import ExtensionApp, ExtensionAppJinjaMixin + + + class MyExtensionApp(ExtensionAppJinjaMixin, ExtensionApp): + ... + + +Pair the example above with ``ExtensionHandlers`` that also inherit the ``ExtensionHandlerJinjaMixin`` mixin. This will automatically load HTML templates from the Jinja templating environment created by the ``ExtensionApp``. + + +.. code-block:: python + + + from jupyter_server.base.handlers import JupyterHandler + from jupyter_server.extension.handler import ( + ExtensionHandlerMixin, + ExtensionHandlerJinjaMixin + ) + + class MyExtensionHandler( + ExtensionHandlerMixin, + ExtensionHandlerJinjaMixin, + JupyterHandler + ): + + def get(self): + ... + + def post(self): + ... + + +.. note:: The mixin classes in this example must come before the base classes, ``ExtensionApp`` and ``ExtensionHandler``. + + +Making an ``ExtensionApp`` discoverable +--------------------------------------- + +To make an ``ExtensionApp`` discoverable by Jupyter Server, add the ``app`` key+value pair to the ``_jupyter_server_extension_paths()`` function example above: + +.. code-block:: python + + from myextension import MyExtensionApp + + + def _jupyter_server_extension_paths(): + """ + Returns a list of dictionaries with metadata describing + where to find the `_load_jupyter_server_extension` function. + """ + return [ + { + "module": "myextension", + "app": MyExtensionApp + } + ] + + +Launching an ``ExtensionApp`` +----------------------------- + +To launch the application, simply call the ``ExtensionApp``'s ``launch_instance`` method. + +.. code-block:: python + + launch_instance = MyFrontend.launch_instance + launch_instance() + + +To make your extension executable from anywhere on your system, point an entry-point at the ``launch_instance`` method in the extension's ``setup.py``: + +.. code-block:: python + + from setuptools import setup + + + setup( + name='myfrontend', + ... + entry_points={ + 'console_scripts': [ + 'jupyter-myextension = myextension:launch_instance' + ] + } + ) + +Distributing a server extension +=============================== + +Putting it all together, authors can distribute their extension following this steps: + +1. Add a ``_jupyter_server_extension_paths()`` function at the extension's root. + This function should likely live in the ``__init__.py`` found at the root of the extension package. It will look something like this: + + .. code-block:: python + + # Found in the __init__.py of package + + def _jupyter_server_extension_paths(): + return [ + { + "module": "myextension.app", + "app": MyExtensionApp + } + ] + +2. Create an extension by writing a ``_load_jupyter_server_extension()`` function or subclassing ``ExtensionApp``. + This is where the extension logic will live (i.e. custom extension handlers, config, etc). See the sections above for more information on how to create an extension. + +3. Add the following JSON config file to the extension package. + The file should be named after the extension (e.g. ``myextension.json``) and saved in a subdirectory of the package with the prefix: ``jupyter-config/jupyter_server_config.d/``. The extension package will have a similar structure to this example: + + .. code-block:: + + myextension + ├── myextension/ + │ ├── __init__.py + │ └── app.py + ├── jupyter-config/ + │ └── jupyter_server_config.d/ + │ └── myextension.json + └── setup.py + + The contents of the JSON file will tell Jupyter Server to load the extension when a user installs the package: + + .. code-block:: json + + { + "ServerApp": { + "jpserver_extensions": { + "myextension": true + } + } + } + + When the extension is installed, this JSON file will be copied to the ``jupyter_server_config.d`` directory found in one of `Jupyter's paths`_. + + Users can toggle the enabling/disableing of extension using the command: + + .. code-block:: console + + jupyter server disable myextension + + which will change the boolean value in the JSON file above. + +4. Create a ``setup.py`` that automatically enables the extension. + Add a few extra lines the extension package's ``setup`` function + + .. code-block:: python + + from setuptools import setup + + setup( + name="myextension", + ... + include_package_data=True, + data_files=[ + ( + "etc/jupyter/jupyter_server_config.d", + ["jupyter-config/jupyter_server_config.d/myextension.json"] + ), + ] + + ) + + +Example Server Extension +======================== + +You can check some simple example on the `GitHub jupyter_server repository +`_. + + + +.. links + +.. _`Jupyter's paths`: https://jupyter.readthedocs.io/en/latest/projects/jupyter-directories.html \ No newline at end of file diff --git a/docs/source/developers/index.rst b/docs/source/developers/index.rst new file mode 100644 index 0000000000..64d0a214d4 --- /dev/null +++ b/docs/source/developers/index.rst @@ -0,0 +1,16 @@ +Documentation for Developers +---------------------------- + +These pages target people writing Jupyter Web applications and server extensions, or people who need to dive deeper in Jupyter Server's REST API and configuration system. + +.. toctree:: + :caption: Developers + :maxdepth: 1 + :name: developers + + dependency + rest-api + extensions + savehooks + contents + ../other/changelog \ No newline at end of file diff --git a/docs/source/developers/rest-api.rst b/docs/source/developers/rest-api.rst new file mode 100644 index 0000000000..f98b6ef6da --- /dev/null +++ b/docs/source/developers/rest-api.rst @@ -0,0 +1,4 @@ +The REST API +============ + +.. openapi:: ../../../jupyter_server/services/api/api.yaml \ No newline at end of file diff --git a/docs/source/extending/savehooks.rst b/docs/source/developers/savehooks.rst similarity index 100% rename from docs/source/extending/savehooks.rst rename to docs/source/developers/savehooks.rst diff --git a/docs/source/extending/bundler_extensions.rst b/docs/source/extending/bundler_extensions.rst deleted file mode 100644 index f1095f3fba..0000000000 --- a/docs/source/extending/bundler_extensions.rst +++ /dev/null @@ -1,182 +0,0 @@ -Custom bundler extensions -========================= - -The notebook server supports the writing of *bundler extensions* that -transform, package, and download/deploy notebook files. As a developer, you -need only write a single Python function to implement a bundler. The notebook -server automatically generates a *File -> Download as* or *File -> Deploy as* -menu item in the notebook front-end to trigger your bundler. - -Here are some examples of what you can implement using bundler extensions: - -* Convert a notebook file to a HTML document and publish it as a post on a - blog site -* Create a snapshot of the current notebook environment and bundle that - definition plus notebook into a zip download -* Deploy a notebook as a standalone, interactive `dashboard `_ - -To implement a bundler extension, you must do all of the following: - -* Declare bundler extension metadata in your Python package -* Write a `bundle` function that responds to bundle requests -* Instruct your users on how to enable/disable your bundler extension - -The following sections describe these steps in detail. - -Declaring bundler metadata --------------------------- - -You must provide information about the bundler extension(s) your package -provides by implementing a `_jupyter_bundlerextensions_paths` function. This -function can reside anywhere in your package so long as it can be imported -when enabling the bundler extension. (See :ref:`enabling-bundlers`.) - -.. code:: python - - # in mypackage.hello_bundler - - def _jupyter_bundlerextension_paths(): - """Example "hello world" bundler extension""" - return [{ - 'name': 'hello_bundler', # unique bundler name - 'label': 'Hello Bundler', # human-redable menu item label - 'module_name': 'mypackage.hello_bundler', # module containing bundle() - 'group': 'deploy' # group under 'deploy' or 'download' menu - }] - -Note that the return value is a list. By returning multiple dictionaries in -the list, you allow users to enable/disable sets of bundlers all at once. - -Writing the `bundle` function ------------------------------ - -At runtime, a menu item with the given label appears either in the -*File -> Deploy as* or *File -> Download as* menu depending on the `group` -value in your metadata. When a user clicks the menu item, a new browser tab -opens and notebook server invokes a `bundle` function in the `module_name` -specified in the metadata. - -You must implement a `bundle` function that matches the signature of the -following example: - -.. code:: python - - # in mypackage.hello_bundler - - def bundle(handler, model): - """Transform, convert, bundle, etc. the notebook referenced by the given - model. - - Then issue a Tornado web response using the `handler` to redirect - the user's browser, download a file, show a HTML page, etc. This function - must finish the handler response before returning either explicitly or by - raising an exception. - - Parameters - ---------- - handler : tornado.web.RequestHandler - Handler that serviced the bundle request - model : dict - Notebook model from the configured ContentManager - """ - handler.finish('I bundled {}!'.format(model['path'])) - -Your `bundle` function is free to do whatever it wants with the request and -respond in any manner. For example, it may read additional query parameters -from the request, issue a redirect to another site, run a local process (e.g., -`nbconvert`), make a HTTP request to another service, etc. - -The caller of the `bundle` function is `async` and wraps its call with -`jupyter_server.utils.ensure_async`. This behavior means you may -handle the web request synchronously, as in the example above, or -asynchronously using `async` and `await`, as in the example -below. - -.. code:: python - - import asyncio - - async def bundle(handler, model): - # simulate a long running IO op (e.g., deploying to a remote host) - await asyncio.sleep(10) - - # now respond - handler.finish('I spent 10 seconds bundling {}!'.format(model['path'])) - -You should prefer the second, asynchronous approach when your bundle operation -is long-running and would otherwise block the notebook server main loop if -handled synchronously. - -For more details about the data flow from menu item click to bundle function -invocation, see :ref:`bundler-details`. - -.. _enabling-bundlers: - -Enabling/disabling bundler extensions -------------------------------------- - -The notebook server includes a command line interface (CLI) for enabling and -disabling bundler extensions. - -You should document the basic commands for enabling and disabling your -bundler. One possible command for enabling the `hello_bundler` example is the -following: - -.. code:: bash - - jupyter bundlerextension enable --py mypackage.hello_bundler --sys-prefix - -The above updates the notebook configuration file in the current -conda/virtualenv environment (`--sys-prefix`) with the metadata returned by -the `mypackage.hellow_bundler._jupyter_bundlerextension_paths` function. - -The corresponding command to later disable the bundler extension is the -following: - -.. code:: bash - - jupyter bundlerextension disable --py mypackage.hello_bundler --sys-prefix - -For more help using the `bundlerextension` subcommand, run the following. - -.. code:: bash - - jupyter bundlerextension --help - -The output describes options for listing enabled bundlers, configuring -bundlers for single users, configuring bundlers system-wide, etc. - -Example: IPython Notebook bundle (.zip) ---------------------------------------- - -The `hello_bundler` example in this documentation is simplisitic in the name -of brevity. For more meaningful examples, see -`jupyter_server/bundler/zip_bundler.py` and `jupyter_server/bundler/tarball_bundler.py`. -You can enable them to try them like so: - -.. code:: bash - - jupyter bundlerextension enable --py jupyter_server.bundler.zip_bundler --sys-prefix - jupyter bundlerextension enable --py jupyter_server.bundler.tarball_bundler --sys-prefix - -.. _bundler-details: - -Bundler invocation details --------------------------- - -Support for bundler extensions comes from Python modules in `jupyter_server/bundler` -and JavaScript in `jupyter_server/static/notebook/js/menubar.js`. The flow of data -between the various components proceeds roughly as follows: - -1. User opens a notebook document -2. Notebook front-end JavaScript loads notebook configuration -3. Bundler front-end JS creates menu items for all bundler extensions in the - config -4. User clicks a bundler menu item -5. JS click handler opens a new browser window/tab to - `/bundle/?bundler=` (i.e., a - HTTP GET request) -6. Bundle handler validates the notebook path and bundler `name` -7. Bundle handler delegates the request to the `bundle` function in the - bundler's `module_name` -8. `bundle` function finishes the HTTP request diff --git a/docs/source/extending/handlers.rst b/docs/source/extending/handlers.rst deleted file mode 100644 index ed6e86697f..0000000000 --- a/docs/source/extending/handlers.rst +++ /dev/null @@ -1,127 +0,0 @@ -Custom request handlers -======================= - -The notebook webserver can be interacted with using a well `defined -RESTful -API `__. -You can define custom RESTful API handlers in addition to the ones -provided by the notebook. As described below, to define a custom handler -you need to first write a notebook server extension. Then, in the -extension, you can register the custom handler. - -Writing a notebook server extension ------------------------------------ - -The notebook webserver is written in Python, hence your server extension -should be written in Python too. Server extensions, like IPython -extensions, are Python modules that define a specially named load -function, ``load_jupyter_server_extension``. This function is called -when the extension is loaded. - -.. code:: python - - def load_jupyter_server_extension(nb_server_app): - """ - Called when the extension is loaded. - - Args: - nb_server_app (NotebookWebApplication): handle to the Notebook webserver instance. - """ - pass - -To get the notebook server to load your custom extension, you'll need to -add it to the list of extensions to be loaded. You can do this using the -config system. ``NotebookApp.jpserver_extensions`` is a config variable -which is a dictionary of strings, each a Python module to be imported, mapping -to ``True`` to enable or ``False`` to disable each extension. -Because this variable is notebook config, you can set it two different -ways, using config files or via the command line. - -For example, to get your extension to load via the command line add a -double dash before the variable name, and put the Python dictionary in -double quotes. If your package is "mypackage" and module is -"mymodule", this would look like -``jupyter notebook --NotebookApp.jpserver_extensions="{'mypackage.mymodule':True}"`` -. -Basically the string should be Python importable. - -Alternatively, you can have your extension loaded regardless of the -command line args by setting the variable in the Jupyter config file. -The default location of the Jupyter config file is -``~/.jupyter/jupyter_notebook_config.py`` (see :doc:`/config_overview`). Inside -the config file, you can use Python to set the variable. For example, -the following config does the same as the previous command line example. - -.. code:: python - - c = get_config() - c.NotebookApp.jpserver_extensions = { - 'mypackage.mymodule': True, - } - -Before continuing, it's a good idea to verify that your extension is -being loaded. Use a print statement to print something unique. Launch -the notebook server and you should see your statement printed to the -console. - -Registering custom handlers ---------------------------- - -Once you've defined a server extension, you can register custom handlers -because you have a handle to the Notebook server app instance -(``nb_server_app`` above). However, you first need to define your custom -handler. To declare a custom handler, inherit from -``notebook.base.handlers.IPythonHandler``. The example below[1] is a -Hello World handler: - -.. code:: python - - from notebook.base.handlers import IPythonHandler - - class HelloWorldHandler(IPythonHandler): - def get(self): - self.finish('Hello, world!') - -The Jupyter Notebook server use -`Tornado `__ as its web framework. -For more information on how to implement request handlers, refer to the -`Tornado documentation on the -matter `__. - -After defining the handler, you need to register the handler with the -Notebook server. See the following example: - -.. code:: python - - web_app = nb_server_app.web_app - host_pattern = '.*$' - route_pattern = url_path_join(web_app.settings['base_url'], '/hello') - web_app.add_handlers(host_pattern, [(route_pattern, HelloWorldHandler)]) - -Putting this together with the extension code, the example looks like the -following: - -.. code:: python - - from notebook.utils import url_path_join - from notebook.base.handlers import IPythonHandler - - class HelloWorldHandler(IPythonHandler): - def get(self): - self.finish('Hello, world!') - - def load_jupyter_server_extension(nb_server_app): - """ - Called when the extension is loaded. - - Args: - nb_server_app: handle to the Notebook webserver instance. - """ - web_app = nb_server_app.web_app - host_pattern = '.*$' - route_pattern = url_path_join(web_app.settings['base_url'], '/hello') - web_app.add_handlers(host_pattern, [(route_pattern, HelloWorldHandler)]) - -References: - -1. `Peter Parente's Mindtrove `__ diff --git a/docs/source/extending/index.rst b/docs/source/extending/index.rst deleted file mode 100644 index 552890d079..0000000000 --- a/docs/source/extending/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -====================== -Extending the Notebook -====================== - -Certain subsystems of the notebook server are designed to be extended or -overridden by users. These documents explain these systems, and show how to -override the notebook's defaults with your own custom behavior. - -.. toctree:: - :maxdepth: 2 - - contents - savehooks - handlers - bundler_extensions diff --git a/docs/source/frontends.rst b/docs/source/frontends.rst deleted file mode 100644 index eaa23f43fa..0000000000 --- a/docs/source/frontends.rst +++ /dev/null @@ -1,144 +0,0 @@ -Creating a Jupyter Server Frontend -================================== - -Jupyter Server does not come with a frontend out-of-the-box; instead, a frontend is installed separately and loaded as a server extension. This page demonstrates the best way to write a Jupyter Server frontend from scratch. - -.. note:: This documentation is written for experienced developers. - - -.. _frontend: - -Writing a frontend application ------------------------------- - -Jupyter Server provides two key classes for writing a server frontend: - - - ``ExtensionApp`` - - ``ExtensionHandlerMixin`` - -The ExtensionApp: - - - can have traits. - - is configurable (from file or CLI) - - creates a namespace for the frontend's static files under ``/static//``. - - loads itself as a server extension beside other Jupyter frontends and extensions. - - provides a command-line interface to launch the frontend extension directly (starting a server along the way). - -To create a new Jupyter frontend application, subclass the ``ExtensionApp`` like the example below: - -.. code-block:: python - - from jupyter_server.extension.application import ExtensionApp - - - class MyFrontend(ExtensionApp): - - # -------------- Required traits -------------- - name = 'myfrontend' - default_url = 'myfrontend' - load_other_extensions = True - - # --- ExtensionApp traits you can configure --- - static_paths = [...] - template_paths = [...] - settings = {...} - handlers = [...] - - # ----------- add custom traits below --------- - ... - - def initialize_settings(self): - ... - # Update the self.settings trait to pass extra - # settings to the underlying Tornado Web Application. - self.settings.update({'':...}) - - def initialize_handlers(self): - ... - # Extend the self.handlers trait - self.handlers.extend(...) - - def initialize_templates(self): - ... - # Change the jinja templating environment - self.settings.update({'myfrontend_jinja2_env': ...}) - -The ``ExtensionApp`` uses the following methods and properties to connect your frontend to the Jupyter server. Overwrite these pieces to add your custom settings, handlers and templates: - -Methods - -* ``initialize_setting()``: adds custom settings to the Tornado Web Application. -* ``initialize_handlers()``: appends handlers to the Tornado Web Application. -* ``initialize_templates()``: initialize the templating engine (e.g. jinja2) for your frontend. - -Properties - -* ``name``: the name of the extension -* ``default_url``: the url that your extension will serve its homepage. -* ``load_other_extensions``: should your extension expose other server extensions when launched directly? - - -Writing frontend handlers -------------------------- - -To write handlers for an ``ExtensionApp``, use the ``ExtensionHandlerMixin`` class. This class routes Tornado's ``static_url`` attribute to the ``/static//`` namespace where your frontend's static files will be served. - -.. code-block:: python - - from jupyter_server.extension.handler import ExtensionHandlerMixin - - class MyFrontendHandler(ExtensionHandlerMixin, JupyterHandler): - - urls = ['/myfrontend/hello'] - - def get(self): - ... - - def post(self): - ... - -ExtensionHandlerMixin comes with the following properties: - -* ``config``: the ExtensionApp's config object. -* ``server_config``: the ServerApp's config object. -* ``extension_name``: the name of the extension to which this handler is linked. -* ``static_url()``: a method for getting the url to static files (prefixed with ``/static/``). - -Launching the application -------------------------- - -To launch the application, simply call the ``ExtensionApp``'s ``launch_instance`` method. - -.. code-block:: python - - main = MyFrontend.launch_instance - main() - - -To make your frontend executable from anywhere on your system, added this method as an entry-point in your application's ``setup.py``: - -.. code-block:: python - - from setuptools import setup - - - setup( - name='myfrontend', - ... - entry_points={ - 'console_scripts': [ - 'jupyter-myfrontend = myfrontend.app:main' - ] - } - ) - -Examples --------- - -You can check some simple example on the `GitHub jupyter_server repository -`_. - -Extension Repositories ----------------------- - -We invite developers to tag the extension repositories with ``jupyter-server-extension``. diff --git a/docs/source/index.rst b/docs/source/index.rst index 7719e2f1bd..9bf8fc3ce7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,45 +1,46 @@ -================================== -Jupyter Server (Developer Preview) -================================== +Welcome! +======== -Jupyter Server is a fork of the `Jupyter Notebook`_'s Tornado_ Server. It provides all the core services, APIs and `REST endpoints`_ from the classic Notebook Server without the Jupyter Notebook (Javascript) frontend. In fact, the Jupyter Server provides no frontend out-of-the-box; rather, it exposes `hooks `_ for Jupyter frontend creators to register their frontends with the Server. +You've landed on the documentation pages for the **Jupyter Server** Project. Some other pages you may have been looking for: -Before the Jupyter Server project, the `Jupyter Notebook`_ was the only first-class frontend to the Tornado Server. As a consequence, other Jupyter frontends had to include Jupyter Notebook (and all of its Javascript code) as a dependency. The Jupyter Server project views all frontends—including the `Jupyter Notebook`_—as equal and separate . +* `Jupyter Server Github Repo `_ +* `JupyterLab Github Repo `_ +* `Jupyter Notebook Github Repo `_ -.. _Tornado: https://www.tornadoweb.org/en/stable/ -.. _Jupyter Notebook: https://github.com/jupyter/notebook -.. _REST endpoints: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml -Installation +Introduction ------------ -To install the latest release of ``jupyter_server``, use *pip*: +Jupyter Server is the backend—the core services, APIs, and `REST endpoints`_—to Jupyter web applications. -.. code-block:: bash +.. note:: - pip install jupyter_server + 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 `_. +.. _Tornado: https://www.tornadoweb.org/en/stable/ +.. _Jupyter Notebook: https://github.com/jupyter/notebook +.. _REST endpoints: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml -.. toctree:: - :maxdepth: 1 - :caption: Table of Contents +Who's this for? +--------------- - frontends - changelog +The Jupyter Server is a highly technical piece of the Jupyter Stack, so we've separated documentation to help specific personas: -.. toctree:: - :maxdepth: 1 - :caption: Configuration +1. :ref:`Users `: people using Jupyter web applications. +2. :ref:`Operators `: people deploying or serving Jupyter web applications to others. +3. :ref:`Developers `: people writing Jupyter Server extensions and web applications. +4. :ref:`Contributors `: people contributing directly to the Jupyter Server library. + +If you finds gaps in our documentation, please open an issue (or better, a pull request) on the Jupyter Server `Github repo `_. - config_overview - config - migrate_from_notebook - public_server - security - extending/index.rst +Table of Contents +----------------- .. toctree:: - :maxdepth: 1 - :caption: Contributor Documentation + :maxdepth: 2 - contributing \ No newline at end of file + Users + Operators + Developers + Contributors + Other \ No newline at end of file diff --git a/docs/source/migrate_from_notebook.rst b/docs/source/migrate_from_notebook.rst deleted file mode 100644 index 4def01c8fe..0000000000 --- a/docs/source/migrate_from_notebook.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. _migrate_from_notebook: - -Migrate from Notebook -===================== - -To migrate from notebook server to plain jupyter server, follow these steps: - -- Rename your ``jupyter_notebook_config.py`` file to ``jupyter_server_config.py``. -- Rename all ``c.NotebookApp`` traits to ``c.ServerApp``. - -For example if you have the following ``jupyter_notebook_config.py``. - -.. code-block:: python - - c.NotebookApp.allow_credentials = False - c.NotebookApp.port = 8889 - c.NotebookApp.password_required = True - - -You will have to create the following ``jupyter_server_config.py`` file. - -.. code-block:: python - - c.ServerApp.allow_credentials = False - c.ServerApp.port = 8889 - c.ServerApp.password_required = True diff --git a/docs/source/operators/configuring-extensions.rst b/docs/source/operators/configuring-extensions.rst new file mode 100644 index 0000000000..ac564f85c8 --- /dev/null +++ b/docs/source/operators/configuring-extensions.rst @@ -0,0 +1,59 @@ +.. _configure-multiple-extensions: + +Configuring Extensions +====================== + +Some Jupyter Server extensions are also configurable applications. There are two ways to configure such extensions: i) pass arguments to the extension's entry point or ii) list configurable options in a Jupyter config file. + +Jupyter Server looks for an extension's config file in a set of specific paths. Use the ``jupyter`` entry point to list these paths: + +.. code-block:: console + + > jupyter --paths + + config: + /Users/username/.jupyter + /usr/local/etc/jupyter + /etc/jupyter + data: + /Users/username/Library/Jupyter + /usr/local/share/jupyter + /usr/share/jupyter + runtime: + /Users/username/Library/Jupyter/runtime + + +Extension config from file +-------------------------- + +Jupyter Server expects the file to be named after the extension's name like so: ``jupyter_{extension_name}_config``. For example, the Jupyter Notebook's config file is ``jupyter_notebook_config``. + +Configuration files can be Python or JSON files. + +In Python config files, each trait will be prefixed with ``c.`` that links the trait to the config loader. For example, Jupyter Notebook config might look like: + +.. code-block:: python + + # jupyter_notebook_config.py + + c.NotebookApp.mathjax_enabled = False + + +A Jupyter Server will automatically load config for each enabled extension. You can configure each extension by creating their corresponding Jupyter config file. + + +Extension config on the command line +------------------------------------ + +Server extension applications can also be configured from the command line, and multiple extension can be configured at the same time. Simply pass the traits (with their appropriate prefix) to the ``jupyter server`` entrypoint, e.g.: + +.. code-block:: console + + > jupyter server --ServerApp.port=9999 --MyExtension1.trait=False --MyExtension2.trait=True + + +This will also work with any extension entrypoints that allow other extensions to run side-by-side, e.g.: + +.. code-block:: console + + > jupyter myextension --ServerApp.port=9999 --MyExtension1.trait=False --MyExtension2.trait=True \ No newline at end of file diff --git a/docs/source/operators/index.rst b/docs/source/operators/index.rst new file mode 100644 index 0000000000..a654be1a0c --- /dev/null +++ b/docs/source/operators/index.rst @@ -0,0 +1,15 @@ +Documentation for Operators +=========================== + +These pages are targeted at people using, configuring, and/or deploying multiple Jupyter Web Application with Jupyter Server. + +.. toctree:: + :caption: Operators + :maxdepth: 1 + :name: operators + + multiple-extensions + configuring-extensions + migrate-from-nbserver + public-server + security \ No newline at end of file diff --git a/docs/source/operators/migrate-from-nbserver.rst b/docs/source/operators/migrate-from-nbserver.rst new file mode 100644 index 0000000000..2ee6ffa50a --- /dev/null +++ b/docs/source/operators/migrate-from-nbserver.rst @@ -0,0 +1,36 @@ +.. _migrate_from_notebook: + +Migrating from Notebook Server +============================== + +To migrate from notebook server to plain jupyter server, follow these steps: + +- Rename your ``jupyter_notebook_config.py`` file to ``jupyter_server_config.py``. +- Rename all ``c.NotebookApp`` traits to ``c.ServerApp``. + +For example if you have the following ``jupyter_notebook_config.py``. + +.. code-block:: python + + c.NotebookApp.allow_credentials = False + c.NotebookApp.port = 8889 + c.NotebookApp.password_required = True + + +You will have to create the following ``jupyter_server_config.py`` file. + +.. code-block:: python + + c.ServerApp.allow_credentials = False + c.ServerApp.port = 8889 + c.ServerApp.password_required = True + + +Running Jupyter Notebook on Jupyter Server +========================================== + +If you want to switch to Jupyter Server, but you still want to serve `Jupyter Notebook `_ to users, you can try `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. + +.. warning:: NBClassic will only work for a limited time. Jupyter Server is likely to evolve beyond a point where Jupyter Notebook frontend will no longer work with the underlying server. Consider switching to `JupyterLab `_ or `nteract `_ where there is active development happening. \ No newline at end of file diff --git a/docs/source/operators/multiple-extensions.rst b/docs/source/operators/multiple-extensions.rst new file mode 100644 index 0000000000..0579e8eafc --- /dev/null +++ b/docs/source/operators/multiple-extensions.rst @@ -0,0 +1,89 @@ + +.. _managing-multiple-extensions: + +Managing multiple extensions +---------------------------- + +One of the major benefits of Jupyter Server is that you can run serve multiple Jupyter frontend applications above the same Tornado web server. That's because every Jupyter frontend application is now a server extension. When you run a Jupyter Server will multiple extensions enabled, each extension appends its own set of handlers and static assets to the server. + +Listing extensions +~~~~~~~~~~~~~~~~~~ + +When you install a Jupyter Server extension, it *should* automatically add itself to your list of enabled extensions. You can see a list of installed extensions by calling: + +.. code-block:: console + + > jupyter server extension list + + config dir: /Users/username/etc/jupyter + myextension enabled + - Validating myextension... + myextension OK + +Enabling/disabling extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You enable/disable an extension using the following commands: + +.. code-block:: console + + > jupyter server extension enable myextension + + Enabling: myextension + - Validating myextension... + myextension OK + - Extension successfully enabled. + + + > jupyter server extension disable myextension + + Disabling: jupyter_home + - Validating jupyter_home... + jupyter_home OK + - Extension successfully disabled. + + +Running an extensions from its entrypoint +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Extensions that are also Jupyter applications (i.e. Notebook, JupyterLab, Voila, etc.) can be launched +from a CLI entrypoint. For example, launch Jupyter Notebook using: + +.. code-block:: console + + > jupyter notebook + + +Jupyter Server will automatically start a server and the browser will be routed to Jupyter Notebook's default URL (typically, ``/tree``). + +Other enabled extension will still be available to the user. The entrypoint simply offers a more direct (backwards compatible) launching mechanism. + +Launching a server with multiple extensions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If multiple extensions are enabled, a Jupyter Server can be launched directly: + +.. code-block:: console + + > jupyter server + + [I 2020-03-23 15:44:53.290 ServerApp] Serving notebooks from local directory: /Users/username/path + [I 2020-03-23 15:44:53.290 ServerApp] Jupyter Server 0.3.0.dev is running at: + [I 2020-03-23 15:44:53.290 ServerApp] http://localhost:8888/?token=<...> + [I 2020-03-23 15:44:53.290 ServerApp] or http://127.0.0.1:8888/?token=<...> + [I 2020-03-23 15:44:53.290 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation). + [I 2020-03-23 15:44:53.290 ServerApp] Welcome to Project Jupyter! Explore the various tools available and their corresponding documentation. If you are interested in contributing to the platform, please visit the communityresources section at https://jupyter.org/community.html. + [C 2020-03-23 15:44:53.296 ServerApp] + + To access the server, open this file in a browser: + file:///Users/username/pathjpserver-####-open.html + Or copy and paste one of these URLs: + http://localhost:8888/?token=<...> + or http://127.0.0.1:8888/?token=<...> + + +Extensions can also be enabled manually from the Jupyter Server entrypoint using the ``jpserver_extensions`` trait: + +.. code-block:: console + + > jupyter server --ServerApp.jpserver_extensions='{"myextension":{"enabled": True}}' diff --git a/docs/source/public_server.rst b/docs/source/operators/public-server.rst similarity index 96% rename from docs/source/public_server.rst rename to docs/source/operators/public-server.rst index 27c5643314..cfe75fdb44 100644 --- a/docs/source/public_server.rst +++ b/docs/source/operators/public-server.rst @@ -1,22 +1,21 @@ .. _working_remotely: -Running a Jupyter server -======================== +Running a public Jupyter Server +=============================== -The Jupyter Server's web application is based on a -server-client structure. The notebook server uses a :ref:`two-process kernel +The Jupyter Server uses a :ref:`two-process kernel architecture ` based on ZeroMQ_, as well as Tornado_ for serving HTTP requests. .. note:: - By default, a notebook server runs locally at 127.0.0.1:8888 + By default, Jupyter Server runs locally at 127.0.0.1:8888 and is accessible only from `localhost`. You may access the - notebook server from the browser using `http://127.0.0.1:8888`. + server from the browser using `http://127.0.0.1:8888`. This document describes how you can -:ref:`secure a notebook server ` and how to -:ref:`run it on a public interface `. +:ref:`secure a Jupyter server ` and how to +:ref:`run it on a public interface `. .. important:: @@ -25,7 +24,7 @@ This document describes how you can only be done by someone who wants remote access to their personal machine. Even so, doing this requires a thorough understanding of the set-ups limitations and security implications. If you allow multiple users to - access a notebook server as it is described in this document, their + access a Jupyter server as it is described in this document, their commands may collide, clobber and overwrite each other. If you want a multi-user server, the official solution is JupyterHub_. @@ -42,7 +41,7 @@ This document describes how you can .. _JupyterHub: https://jupyterhub.readthedocs.io/en/latest/ -.. _notebook_server_security: +.. _Jupyter_server_security: Securing a Jupyter server ------------------------- @@ -184,7 +183,7 @@ public server. .. _OWASP: https://www.owasp.org/index.php/Main_Page .. _tutorial: https://arstechnica.com/information-technology/2009/12/how-to-get-set-with-a-secure-sertificate-for-free/ -.. _notebook_public_server: +.. _jupyter_public_server: Running a public notebook server -------------------------------- @@ -193,10 +192,10 @@ If you want to access your notebook server remotely via a web browser, you can do so by running a public notebook server. For optimal security when running a public notebook server, you should first secure the server with a password and SSL/HTTPS as described in -:ref:`notebook_server_security`. +:ref:`jupyter_server_security`. Start by creating a certificate file and a hashed password, as explained in -:ref:`notebook_server_security`. +:ref:`jupyter_server_security`. If you don't already have one, create a config file for the notebook using the following command line:: @@ -230,7 +229,7 @@ Using Let's Encrypt `Let's Encrypt`_ provides free SSL/TLS certificates. You can also set up a public server using a `Let's Encrypt`_ certificate. -:ref:`notebook_public_server` will be similar when using a Let's Encrypt +:ref:`jupyter_public_server` will be similar when using a Let's Encrypt certificate with a few configuration changes. Here are the steps: 1. Create a `Let's Encrypt certificate `_. diff --git a/docs/source/security.rst b/docs/source/operators/security.rst similarity index 100% rename from docs/source/security.rst rename to docs/source/operators/security.rst diff --git a/docs/source/changelog.rst b/docs/source/other/changelog.rst similarity index 100% rename from docs/source/changelog.rst rename to docs/source/other/changelog.rst diff --git a/docs/source/other/faq.rst b/docs/source/other/faq.rst new file mode 100644 index 0000000000..507eea942b --- /dev/null +++ b/docs/source/other/faq.rst @@ -0,0 +1,14 @@ +.. _faq: + + +Frequently asked questions +========================== + +Here is a list of questions we think you might have. This list will always be growing, so please feel free to add your question+anwer to this page! |:rocket:| + + +Can I configure multiple extensions at once? +-------------------------------------------- + +Checkout our "Operator" docs on how to :ref:`configure extensions `. |:closed_book:| + diff --git a/docs/source/other/full-config.rst b/docs/source/other/full-config.rst new file mode 100644 index 0000000000..f7f0cab4ba --- /dev/null +++ b/docs/source/other/full-config.rst @@ -0,0 +1,1031 @@ +.. _other-full-config: + + +Config file and command line options +==================================== + +The Jupyter Server can be run with a variety of command line arguments. +A list of available options can be found below in the :ref:`options section +`. + +Defaults for these options can also be set by creating a file named +``jupyter_server_config.py`` in your Jupyter folder. The Jupyter +folder is in your home directory, ``~/.jupyter``. + +To create a ``jupyter_server_config.py`` file, with all the defaults +commented out, you can use the following command line:: + + $ jupyter server --generate-config + + +.. _options: + +Options +------- + +This list of options can be generated by running the following and hitting +enter:: + + $ jupyter server --help-all + + + + +Application.log_datefmt : Unicode + Default: ``'%Y-%m-%d %H:%M:%S'`` + + The date format used by logging formatters for %(asctime)s + +Application.log_format : Unicode + Default: ``'[%(name)s]%(highlevel)s %(message)s'`` + + The Logging format template + +Application.log_level : 0|10|20|30|40|50|'DEBUG'|'INFO'|'WARN'|'ERROR'|'CRITICAL' + Default: ``30`` + + Set the log level by value or name. + +JupyterApp.answer_yes : Bool + Default: ``False`` + + Answer yes to any prompts. + +JupyterApp.config_file : Unicode + Default: ``''`` + + Full path of a config file. + +JupyterApp.config_file_name : Unicode + Default: ``''`` + + Specify a config file to load. + +JupyterApp.generate_config : Bool + Default: ``False`` + + Generate default config file. + +ServerApp.allow_credentials : Bool + Default: ``False`` + + Set the Access-Control-Allow-Credentials: true header + +ServerApp.allow_origin : Unicode + Default: ``''`` + + Set the Access-Control-Allow-Origin header + + Use '*' to allow any origin to access your server. + + Takes precedence over allow_origin_pat. + + +ServerApp.allow_origin_pat : Unicode + Default: ``''`` + + Use a regular expression for the Access-Control-Allow-Origin header + + Requests from an origin matching the expression will get replies with: + + Access-Control-Allow-Origin: origin + + where `origin` is the origin of the request. + + Ignored if allow_origin is set. + + +ServerApp.allow_password_change : Bool + Default: ``True`` + + Allow password to be changed at login for the Jupyter server. + + While loggin in with a token, the Jupyter server UI will give the opportunity to + the user to enter a new password at the same time that will replace + the token login mechanism. + + This can be set to false to prevent changing password from the UI/API. + + +ServerApp.allow_remote_access : Bool + Default: ``False`` + + Allow requests where the Host header doesn't point to a local server + + By default, requests get a 403 forbidden response if the 'Host' header + shows that the browser thinks it's on a non-local domain. + Setting this option to True disables this check. + + This protects against 'DNS rebinding' attacks, where a remote web server + serves you a page and then changes its DNS to send later requests to a + local IP, bypassing same-origin checks. + + Local IP addresses (such as 127.0.0.1 and ::1) are allowed as local, + along with hostnames configured in local_hostnames. + + +ServerApp.allow_root : Bool + Default: ``False`` + + Whether to allow the user to run the server as root. + +ServerApp.base_url : Unicode + Default: ``'/'`` + + The base URL for the Jupyter server. + + Leading and trailing slashes can be omitted, + and will automatically be added. + + +ServerApp.browser : Unicode + Default: ``''`` + + Specify what command to use to invoke a web + browser when starting the server. If not specified, the + default browser will be determined by the `webbrowser` + standard library module, which allows setting of the + BROWSER environment variable to override it. + + +ServerApp.certfile : Unicode + Default: ``''`` + + The full path to an SSL/TLS certificate file. + +ServerApp.client_ca : Unicode + Default: ``''`` + + The full path to a certificate authority certificate for SSL/TLS client authentication. + +ServerApp.config_manager_class : Type + Default: ``'jupyter_server.services.config.manager.ConfigManager'`` + + The config manager class to use + +ServerApp.contents_manager_class : Type + Default: ``'jupyter_server.services.contents.largefilemanager.LargeFileM...`` + + The content manager class to use. + +ServerApp.cookie_options : Dict + Default: ``{}`` + + Extra keyword arguments to pass to `set_secure_cookie`. See tornado's set_secure_cookie docs for details. + +ServerApp.cookie_secret : Bytes + Default: ``b''`` + + The random bytes used to secure cookies. + By default this is a new random number every time you start the server. + Set it to a value in a config file to enable logins to persist across server sessions. + + Note: Cookie secrets should be kept private, do not share config files with + cookie_secret stored in plaintext (you can read the value from a file). + + +ServerApp.cookie_secret_file : Unicode + Default: ``''`` + + The file where the cookie secret is stored. + +ServerApp.custom_display_url : Unicode + Default: ``''`` + + Override URL shown to users. + + Replace actual URL, including protocol, address, port and base URL, + with the given value when displaying URL to the users. Do not change + the actual connection URL. If authentication token is enabled, the + token is added to the custom URL automatically. + + This option is intended to be used when the URL to display to the user + cannot be determined reliably by the Jupyter server (proxified + or containerized setups for example). + +ServerApp.default_url : Unicode + Default: ``'/'`` + + The default URL to redirect to from `/` + +ServerApp.disable_check_xsrf : Bool + Default: ``False`` + + Disable cross-site-request-forgery protection + + Jupyter notebook 4.3.1 introduces protection from cross-site request forgeries, + requiring API requests to either: + + - originate from pages served by this server (validated with XSRF cookie and token), or + - authenticate with a token + + Some anonymous compute resources still desire the ability to run code, + completely without authentication. + These services can disable all authentication and security checks, + with the full knowledge of what that implies. + + +ServerApp.extra_services : List + Default: ``[]`` + + handlers that should be loaded at higher priority than the default services + +ServerApp.extra_static_paths : List + Default: ``[]`` + + Extra paths to search for serving static files. + + This allows adding javascript/css to be available from the Jupyter server machine, + or overriding individual files in the IPython + +ServerApp.extra_template_paths : List + Default: ``[]`` + + Extra paths to search for serving jinja templates. + + Can be used to override templates from jupyter_server.templates. + +ServerApp.file_to_run : Unicode + Default: ``''`` + + No description + +ServerApp.get_secure_cookie_kwargs : Dict + Default: ``{}`` + + Extra keyword arguments to pass to `get_secure_cookie`. See tornado's get_secure_cookie docs for details. + +ServerApp.iopub_data_rate_limit : Float + Default: ``1000000`` + + (bytes/sec) + Maximum rate at which stream output can be sent on iopub before they are + limited. + +ServerApp.iopub_msg_rate_limit : Float + Default: ``1000`` + + (msgs/sec) + Maximum rate at which messages can be sent on iopub before they are + limited. + +ServerApp.ip : Unicode + Default: ``'localhost'`` + + The IP address the Jupyter server will listen on. + +ServerApp.jinja_environment_options : Dict + Default: ``{}`` + + Supply extra arguments that will be passed to Jinja environment. + +ServerApp.jinja_template_vars : Dict + Default: ``{}`` + + Extra variables to supply to jinja templates when rendering. + +ServerApp.jpserver_extensions : Dict + Default: ``{}`` + + Dict of Python modules to load as notebook server extensions.Entry values can be used to enable and disable the loading ofthe extensions. The extensions will be loaded in alphabetical order. + +ServerApp.kernel_manager_class : Type + Default: ``'jupyter_server.services.kernels.kernelmanager.MappingKernelM...`` + + The kernel manager class to use. + +ServerApp.kernel_spec_manager_class : Type + Default: ``'jupyter_client.kernelspec.KernelSpecManager'`` + + + The kernel spec manager class to use. Should be a subclass + of `jupyter_client.kernelspec.KernelSpecManager`. + + The Api of KernelSpecManager is provisional and might change + without warning between this version of Jupyter and the next stable one. + + +ServerApp.keyfile : Unicode + Default: ``''`` + + The full path to a private key file for usage with SSL/TLS. + +ServerApp.local_hostnames : List + Default: ``['localhost']`` + + Hostnames to allow as local when allow_remote_access is False. + + Local IP addresses (such as 127.0.0.1 and ::1) are automatically accepted + as local as well. + + +ServerApp.login_handler_class : Type + Default: ``'jupyter_server.auth.login.LoginHandler'`` + + The login handler class to use. + +ServerApp.logout_handler_class : Type + Default: ``'jupyter_server.auth.logout.LogoutHandler'`` + + The logout handler class to use. + +ServerApp.max_body_size : Int + Default: ``536870912`` + + + Sets the maximum allowed size of the client request body, specified in + the Content-Length request header field. If the size in a request + exceeds the configured value, a malformed HTTP message is returned to + the client. + + Note: max_body_size is applied even in streaming mode. + + +ServerApp.max_buffer_size : Int + Default: ``536870912`` + + + Gets or sets the maximum amount of memory, in bytes, that is allocated + for use by the buffer manager. + + +ServerApp.notebook_dir : Unicode + Default: ``''`` + + DEPRECATED, use root_dir. + +ServerApp.open_browser : Bool + Default: ``False`` + + Whether to open in a browser after starting. + The specific browser used is platform dependent and + determined by the python standard library `webbrowser` + module, unless it is overridden using the --browser + (ServerApp.browser) configuration option. + + +ServerApp.password : Unicode + Default: ``''`` + + Hashed password to use for web authentication. + + To generate, type in a python/IPython shell: + + from jupyter_server.auth import passwd; passwd() + + The string should be of the form type:salt:hashed-password. + + +ServerApp.password_required : Bool + Default: ``False`` + + Forces users to use a password for the Jupyter server. + This is useful in a multi user environment, for instance when + everybody in the LAN can access each other's machine through ssh. + + In such a case, serving on localhost is not secure since + any user can connect to the Jupyter server via ssh. + + + +ServerApp.port : Int + Default: ``8888`` + + The port the Jupyter server will listen on. + +ServerApp.port_retries : Int + Default: ``50`` + + The number of additional ports to try if the specified port is not available. + +ServerApp.pylab : Unicode + Default: ``'disabled'`` + + + DISABLED: use %pylab or %matplotlib in the notebook to enable matplotlib. + + +ServerApp.quit_button : Bool + Default: ``True`` + + If True, display a button in the dashboard to quit + (shutdown the Jupyter server). + +ServerApp.rate_limit_window : Float + Default: ``3`` + + (sec) Time window used to + check the message and data rate limits. + +ServerApp.reraise_server_extension_failures : Bool + Default: ``False`` + + Reraise exceptions encountered loading server extensions? + +ServerApp.root_dir : Unicode + Default: ``''`` + + The directory to use for notebooks and kernels. + +ServerApp.session_manager_class : Type + Default: ``'jupyter_server.services.sessions.sessionmanager.SessionManager'`` + + The session manager class to use. + +ServerApp.shutdown_no_activity_timeout : Int + Default: ``0`` + + Shut down the server after N seconds with no kernels or terminals running and no activity. This can be used together with culling idle kernels (MappingKernelManager.cull_idle_timeout) to shutdown the Jupyter server when it's not in use. This is not precisely timed: it may shut down up to a minute later. 0 (the default) disables this automatic shutdown. + +ServerApp.ssl_options : Dict + Default: ``{}`` + + Supply SSL options for the tornado HTTPServer. + See the tornado docs for details. + +ServerApp.terminado_settings : Dict + Default: ``{}`` + + Supply overrides for terminado. Currently only supports "shell_command". + +ServerApp.terminals_enabled : Bool + Default: ``True`` + + Set to False to disable terminals. + + This does *not* make the server more secure by itself. + Anything the user can in a terminal, they can also do in a notebook. + + Terminals may also be automatically disabled if the terminado package + is not available. + + +ServerApp.token : Unicode + Default: ``''`` + + Token used for authenticating first-time connections to the server. + + When no password is enabled, + the default is to generate a new, random token. + + Setting to an empty string disables authentication altogether, which is NOT RECOMMENDED. + + +ServerApp.tornado_settings : Dict + Default: ``{}`` + + Supply overrides for the tornado.web.Application that the Jupyter server uses. + +ServerApp.trust_xheaders : Bool + Default: ``False`` + + Whether to trust or not X-Scheme/X-Forwarded-Proto and X-Real-Ip/X-Forwarded-For headerssent by the upstream reverse proxy. Necessary if the proxy handles SSL + +ServerApp.webbrowser_open_new : Int + Default: ``2`` + + Specify where to open the server on startup. This is the + `new` argument passed to the standard library method `webbrowser.open`. + The behaviour is not guaranteed, but depends on browser support. Valid + values are: + + - 2 opens a new tab, + - 1 opens a new window, + - 0 opens in an existing window. + + See the `webbrowser.open` documentation for details. + + +ServerApp.websocket_compression_options : Any + Default: ``None`` + + + Set the tornado compression options for websocket connections. + + This value will be returned from :meth:`WebSocketHandler.get_compression_options`. + None (default) will disable compression. + A dict (even an empty one) will enable compression. + + See the tornado docs for WebSocketHandler.get_compression_options for details. + + +ServerApp.websocket_url : Unicode + Default: ``''`` + + The base URL for websockets, + if it differs from the HTTP server (hint: it almost certainly doesn't). + + Should be in the form of an HTTP origin: ws[s]://hostname[:port] + + +ConnectionFileMixin.connection_file : Unicode + Default: ``''`` + + JSON file in which to store connection info [default: kernel-.json] + + This file will contain the IP, ports, and authentication key needed to connect + clients to this kernel. By default, this file will be created in the security dir + of the current profile, but can be specified by absolute path. + + +ConnectionFileMixin.control_port : Int + Default: ``0`` + + set the control (ROUTER) port [default: random] + +ConnectionFileMixin.hb_port : Int + Default: ``0`` + + set the heartbeat port [default: random] + +ConnectionFileMixin.iopub_port : Int + Default: ``0`` + + set the iopub (PUB) port [default: random] + +ConnectionFileMixin.ip : Unicode + Default: ``''`` + + Set the kernel's IP address [default localhost]. + If the IP address is something other than localhost, then + Consoles on other machines will be able to connect + to the Kernel, so be careful! + +ConnectionFileMixin.shell_port : Int + Default: ``0`` + + set the shell (ROUTER) port [default: random] + +ConnectionFileMixin.stdin_port : Int + Default: ``0`` + + set the stdin (ROUTER) port [default: random] + +ConnectionFileMixin.transport : 'tcp'|'ipc' + Default: ``'tcp'`` + + No description + +KernelManager.autorestart : Bool + Default: ``True`` + + Should we autorestart the kernel if it dies. + +KernelManager.kernel_cmd : List + Default: ``[]`` + + DEPRECATED: Use kernel_name instead. + + The Popen Command to launch the kernel. + Override this if you have a custom kernel. + If kernel_cmd is specified in a configuration file, + Jupyter does not pass any arguments to the kernel, + because it cannot make any assumptions about the + arguments that the kernel understands. In particular, + this means that the kernel does not receive the + option --debug if it given on the Jupyter command line. + + +KernelManager.shutdown_wait_time : Float + Default: ``5.0`` + + Time to wait for a kernel to terminate before killing it, in seconds. + +Session.buffer_threshold : Int + Default: ``1024`` + + Threshold (in bytes) beyond which an object's buffer should be extracted to avoid pickling. + +Session.check_pid : Bool + Default: ``True`` + + Whether to check PID to protect against calls after fork. + + This check can be disabled if fork-safety is handled elsewhere. + + +Session.copy_threshold : Int + Default: ``65536`` + + Threshold (in bytes) beyond which a buffer should be sent without copying. + +Session.debug : Bool + Default: ``False`` + + Debug output in the Session + +Session.digest_history_size : Int + Default: ``65536`` + + The maximum number of digests to remember. + + The digest history will be culled when it exceeds this value. + + +Session.item_threshold : Int + Default: ``64`` + + The maximum number of items for a container to be introspected for custom serialization. + Containers larger than this are pickled outright. + + +Session.key : CBytes + Default: ``b''`` + + execution key, for signing messages. + +Session.keyfile : Unicode + Default: ``''`` + + path to file containing execution key. + +Session.metadata : Dict + Default: ``{}`` + + Metadata dictionary, which serves as the default top-level metadata dict for each message. + +Session.packer : DottedObjectName + Default: ``'json'`` + + The name of the packer for serializing messages. + Should be one of 'json', 'pickle', or an import name + for a custom callable serializer. + +Session.session : CUnicode + Default: ``''`` + + The UUID identifying this session. + +Session.signature_scheme : Unicode + Default: ``'hmac-sha256'`` + + The digest scheme used to construct the message signatures. + Must have the form 'hmac-HASH'. + +Session.unpacker : DottedObjectName + Default: ``'json'`` + + The name of the unpacker for unserializing messages. + Only used with custom functions for `packer`. + +Session.username : Unicode + Default: ``'zsailer'`` + + Username for the Session. Default is your system username. + +MultiKernelManager.default_kernel_name : Unicode + Default: ``'python3'`` + + The name of the default kernel to start + +MultiKernelManager.kernel_manager_class : DottedObjectName + Default: ``'jupyter_client.ioloop.IOLoopKernelManager'`` + + The kernel manager class. This is configurable to allow + subclassing of the KernelManager for customized behavior. + + +MappingKernelManager.allowed_message_types : List + Default: ``[]`` + + White list of allowed kernel message types. + When the list is empty, all message types are allowed. + + +MappingKernelManager.buffer_offline_messages : Bool + Default: ``True`` + + Whether messages from kernels whose frontends have disconnected should be buffered in-memory. + + When True (default), messages are buffered and replayed on reconnect, + avoiding lost messages due to interrupted connectivity. + + Disable if long-running kernels will produce too much output while + no frontends are connected. + + +MappingKernelManager.cull_busy : Bool + Default: ``False`` + + Whether to consider culling kernels which are busy. + Only effective if cull_idle_timeout > 0. + +MappingKernelManager.cull_connected : Bool + Default: ``False`` + + Whether to consider culling kernels which have one or more connections. + Only effective if cull_idle_timeout > 0. + +MappingKernelManager.cull_idle_timeout : Int + Default: ``0`` + + Timeout (in seconds) after which a kernel is considered idle and ready to be culled. + Values of 0 or lower disable culling. Very short timeouts may result in kernels being culled + for users with poor network connections. + +MappingKernelManager.cull_interval : Int + Default: ``300`` + + The interval (in seconds) on which to check for idle kernels exceeding the cull timeout value. + +MappingKernelManager.kernel_info_timeout : Float + Default: ``60`` + + Timeout for giving up on a kernel (in seconds). + + On starting and restarting kernels, we check whether the + kernel is running and responsive by sending kernel_info_requests. + This sets the timeout in seconds for how long the kernel can take + before being presumed dead. + This affects the MappingKernelManager (which handles kernel restarts) + and the ZMQChannelsHandler (which handles the startup). + + +MappingKernelManager.root_dir : Unicode + Default: ``''`` + + No description + +KernelSpecManager.ensure_native_kernel : Bool + Default: ``True`` + + If there is no Python kernelspec registered and the IPython + kernel is available, ensure it is added to the spec list. + + +KernelSpecManager.kernel_spec_class : Type + Default: ``'jupyter_client.kernelspec.KernelSpec'`` + + The kernel spec class. This is configurable to allow + subclassing of the KernelSpecManager for customized behavior. + + +KernelSpecManager.whitelist : Set + Default: ``set()`` + + Whitelist of allowed kernel names. + + By default, all installed kernels are allowed. + + +ContentsManager.allow_hidden : Bool + Default: ``False`` + + Allow access to hidden files + +ContentsManager.checkpoints : Instance + Default: ``None`` + + No description + +ContentsManager.checkpoints_class : Type + Default: ``'jupyter_server.services.contents.checkpoints.Checkpoints'`` + + No description + +ContentsManager.checkpoints_kwargs : Dict + Default: ``{}`` + + No description + +ContentsManager.files_handler_class : Type + Default: ``'jupyter_server.files.handlers.FilesHandler'`` + + handler class to use when serving raw file requests. + + Default is a fallback that talks to the ContentsManager API, + which may be inefficient, especially for large files. + + Local files-based ContentsManagers can use a StaticFileHandler subclass, + which will be much more efficient. + + Access to these files should be Authenticated. + + +ContentsManager.files_handler_params : Dict + Default: ``{}`` + + Extra parameters to pass to files_handler_class. + + For example, StaticFileHandlers generally expect a `path` argument + specifying the root directory from which to serve files. + + +ContentsManager.hide_globs : List + Default: ``['__pycache__', '*.pyc', '*.pyo', '.DS_Store', '*.so', '*.dyl...`` + + + Glob patterns to hide in file and directory listings. + + +ContentsManager.pre_save_hook : Any + Default: ``None`` + + Python callable or importstring thereof + + To be called on a contents model prior to save. + + This can be used to process the structure, + such as removing notebook outputs or other side effects that + should not be saved. + + It will be called as (all arguments passed by keyword):: + + hook(path=path, model=model, contents_manager=self) + + - model: the model to be saved. Includes file contents. + Modifying this dict will affect the file that is stored. + - path: the API path of the save destination + - contents_manager: this ContentsManager instance + + +ContentsManager.root_dir : Unicode + Default: ``'/'`` + + No description + +ContentsManager.untitled_directory : Unicode + Default: ``'Untitled Folder'`` + + The base name used when creating untitled directories. + +ContentsManager.untitled_file : Unicode + Default: ``'untitled'`` + + The base name used when creating untitled files. + +ContentsManager.untitled_notebook : Unicode + Default: ``'Untitled'`` + + The base name used when creating untitled notebooks. + +FileManagerMixin.use_atomic_writing : Bool + Default: ``True`` + + By default notebooks are saved on disk on a temporary file and then if succefully written, it replaces the old ones. + This procedure, namely 'atomic_writing', causes some bugs on file system whitout operation order enforcement (like some networked fs). + If set to False, the new notebook is written directly on the old one which could fail (eg: full filesystem or quota ) + +FileContentsManager.delete_to_trash : Bool + Default: ``True`` + + If True (default), deleting files will send them to the + platform's trash/recycle bin, where they can be recovered. If False, + deleting files really deletes them. + +FileContentsManager.post_save_hook : Any + Default: ``None`` + + Python callable or importstring thereof + + to be called on the path of a file just saved. + + This can be used to process the file on disk, + such as converting the notebook to a script or HTML via nbconvert. + + It will be called as (all arguments passed by keyword):: + + hook(os_path=os_path, model=model, contents_manager=instance) + + - path: the filesystem path to the file just written + - model: the model representing the file + - contents_manager: this ContentsManager instance + + +FileContentsManager.root_dir : Unicode + Default: ``''`` + + No description + +NotebookNotary.algorithm : 'md5'|'sha3_384'|'sha3_512'|'sha256'|'sha1'|'blake2s'|'sha3_256'|'sha3_224'|'sha384'|'sha512'|'blake2b'|'sha224' + Default: ``'sha256'`` + + The hashing algorithm used to sign notebooks. + +NotebookNotary.db_file : Unicode + Default: ``''`` + + The sqlite file in which to store notebook signatures. + By default, this will be in your Jupyter data directory. + You can set it to ':memory:' to disable sqlite writing to the filesystem. + + +NotebookNotary.secret : Bytes + Default: ``b''`` + + The secret key with which notebooks are signed. + +NotebookNotary.secret_file : Unicode + Default: ``''`` + + The file where the secret key is stored. + +NotebookNotary.store_factory : Callable + Default: ``traitlets.Undefined`` + + A callable returning the storage backend for notebook signatures. + The default uses an SQLite database. + + + + + +GatewayClient.auth_token : Unicode + Default: ``None`` + + The authorization token used in the HTTP headers. (JUPYTER_GATEWAY_AUTH_TOKEN env var) + + +GatewayClient.ca_certs : Unicode + Default: ``None`` + + The filename of CA certificates or None to use defaults. (JUPYTER_GATEWAY_CA_CERTS env var) + + +GatewayClient.client_cert : Unicode + Default: ``None`` + + The filename for client SSL certificate, if any. (JUPYTER_GATEWAY_CLIENT_CERT env var) + + +GatewayClient.client_key : Unicode + Default: ``None`` + + The filename for client SSL key, if any. (JUPYTER_GATEWAY_CLIENT_KEY env var) + + +GatewayClient.connect_timeout : Float + Default: ``60.0`` + + The time allowed for HTTP connection establishment with the Gateway server. + (JUPYTER_GATEWAY_CONNECT_TIMEOUT env var) + +GatewayClient.env_whitelist : Unicode + Default: ``''`` + + A comma-separated list of environment variable names that will be included, along with + their values, in the kernel startup request. The corresponding `env_whitelist` configuration + value must also be set on the Gateway server - since that configuration value indicates which + environmental values to make available to the kernel. (JUPYTER_GATEWAY_ENV_WHITELIST env var) + +GatewayClient.headers : Unicode + Default: ``'{}'`` + + Additional HTTP headers to pass on the request. This value will be converted to a dict. + (JUPYTER_GATEWAY_HEADERS env var) + + +GatewayClient.http_pwd : Unicode + Default: ``None`` + + The password for HTTP authentication. (JUPYTER_GATEWAY_HTTP_PWD env var) + + +GatewayClient.http_user : Unicode + Default: ``None`` + + The username for HTTP authentication. (JUPYTER_GATEWAY_HTTP_USER env var) + + +GatewayClient.kernels_endpoint : Unicode + Default: ``'/api/kernels'`` + + The gateway API endpoint for accessing kernel resources (JUPYTER_GATEWAY_KERNELS_ENDPOINT env var) + +GatewayClient.kernelspecs_endpoint : Unicode + Default: ``'/api/kernelspecs'`` + + The gateway API endpoint for accessing kernelspecs (JUPYTER_GATEWAY_KERNELSPECS_ENDPOINT env var) + +GatewayClient.kernelspecs_resource_endpoint : Unicode + Default: ``'/kernelspecs'`` + + The gateway endpoint for accessing kernelspecs resources + (JUPYTER_GATEWAY_KERNELSPECS_RESOURCE_ENDPOINT env var) + +GatewayClient.request_timeout : Float + Default: ``60.0`` + + The time allowed for HTTP request completion. (JUPYTER_GATEWAY_REQUEST_TIMEOUT env var) + +GatewayClient.url : Unicode + Default: ``None`` + + The url of the Kernel or Enterprise Gateway server where + kernel specifications are defined and kernel management takes place. + If defined, this Notebook server acts as a proxy for all kernel + management and kernel specification retrieval. (JUPYTER_GATEWAY_URL env var) + + +GatewayClient.validate_cert : Bool + Default: ``True`` + + For HTTPS requests, determines if server's certificate should be validated or not. + (JUPYTER_GATEWAY_VALIDATE_CERT env var) + +GatewayClient.ws_url : Unicode + Default: ``None`` + + The websocket url of the Kernel or Enterprise Gateway server. If not provided, this value + will correspond to the value of the Gateway url with 'ws' in place of 'http'. (JUPYTER_GATEWAY_WS_URL env var) + diff --git a/docs/source/other/index.rst b/docs/source/other/index.rst new file mode 100644 index 0000000000..651c0d6581 --- /dev/null +++ b/docs/source/other/index.rst @@ -0,0 +1,10 @@ +Other helpful documentation +--------------------------- + +.. toctree:: + :maxdepth: 1 + + links + faq + changelog + full-config \ No newline at end of file diff --git a/docs/source/other/links.rst b/docs/source/other/links.rst new file mode 100644 index 0000000000..935ddc53cb --- /dev/null +++ b/docs/source/other/links.rst @@ -0,0 +1,9 @@ +List of helpful links +===================== + +* :ref:`Frequently Asked Questions ` +* `Jupyter Server Github Repo `_ +* `JupyterLab Github Repo `_ +* `Jupyter Notebook Github Repo `_ +* `Jupyterhub Github Repo `_ +* `Jupyter Zoom Channel `_ diff --git a/docs/source/users/configuration.rst b/docs/source/users/configuration.rst new file mode 100644 index 0000000000..2e150c8cb4 --- /dev/null +++ b/docs/source/users/configuration.rst @@ -0,0 +1,68 @@ +.. _user-configuring-a-jupyter-server: + +Configuring a Jupyter Server +============================ + +Using a Jupyter config file +--------------------------- + +By default, Jupyter Server looks for server-specific configuration in a ``jupyter_server_config`` file located on a Jupyter path. To list the paths where Jupyter Server will look, run: + +.. code-block:: console + + $ jupyter --paths + + config: + /Users/username/.jupyter + /usr/local/etc/jupyter + /etc/jupyter + data: + /Users/username/Library/Jupyter + /usr/local/share/jupyter + /usr/share/jupyter + runtime: + /Users/username/Library/Jupyter/runtime + + +The paths under ``config`` are listed in order of precedence. If the same trait is listed in multiple places, it will be set to the value from the file will highest precendence. + + +Jupyter Server uses IPython's traitlets system for configuration. Traits can be listed in a Python or JSON config file. You can quickly create a ``jupyter_server_config.py`` file in the ``.jupyter`` directory, with all the defaults commented out, use the following command: + +.. code-block:: console + + $ jupyter server --generate-config + +In Python files, these traits will have the prefix ``c.ServerApp``. For example, your configuration file could look like: + +.. code-block:: python + + # inside a jupyter_server_config.py file. + + c.ServerApp.port = 9999 + +The same configuration in JSON, looks like: + +.. code-block:: json + + { + "ServerApp": { + "port": 9999 + } + } + + +Using the CLI +------------- + +Alternatively, you can configure Jupyter Server when launching from the command line using CLI args. Prefix each argument with ``--ServerApp`` like so: + +.. code-block:: console + + $ jupyter server --ServerApp.port=9999 + + +Full configuration list +----------------------- + +See the full list of configuration options for the server :ref:`here `. \ No newline at end of file diff --git a/docs/source/users/help.rst b/docs/source/users/help.rst new file mode 100644 index 0000000000..a149d40e9a --- /dev/null +++ b/docs/source/users/help.rst @@ -0,0 +1,8 @@ +.. _user-getting-help: + +Getting Help +============ + +If you run into any issues or bugs, please open an `issue on Github `_. + +We'd also love to have you come by our :ref:`Team Meetings `. \ No newline at end of file diff --git a/docs/source/users/index.rst b/docs/source/users/index.rst new file mode 100644 index 0000000000..62675c2748 --- /dev/null +++ b/docs/source/users/index.rst @@ -0,0 +1,14 @@ +Documentation for Users +======================= + +The Jupyter Server is a highly technical piece of the Jupyter Stack, so users probably won't import or install this library directly. These pages are to meant to help you in case you run into issues or bugs. + + +.. toctree:: + :maxdepth: 1 + :name: users + + installation + configuration + launching + help \ No newline at end of file diff --git a/docs/source/users/installation.rst b/docs/source/users/installation.rst new file mode 100644 index 0000000000..14bef0a74f --- /dev/null +++ b/docs/source/users/installation.rst @@ -0,0 +1,22 @@ +.. _user-installation: + +Installation +============ + +Most Jupyter users will **never need to install Jupyter Server manually**. Jupyter Web applications will include the (correct version) of Jupyter Server as a dependency. It's best to let those applications handle installation, because they may require a specific version of Jupyter Server. + +If you decide to install manually, run: + +.. code-block:: bash + + pip install jupyter_server + + +You upgrade or downgrade to a specific version of Jupyter Server by adding an operator to the command above: + +.. code-block:: bash + + pip install jupyter_server==1.0 + + +To see what each version has to offer, checkout our :ref:`changelog`. diff --git a/docs/source/users/launching.rst b/docs/source/users/launching.rst new file mode 100644 index 0000000000..b90fb3eea0 --- /dev/null +++ b/docs/source/users/launching.rst @@ -0,0 +1,26 @@ +.. _user-launching-a-bare-jupyter-server: + +Launching a bare Jupyter Server +=============================== + +Most of the time, you won't need to start the Jupyter Server directly. Jupyter Web Applications (like Jupyter Notebook, Jupyterlab, Voila, etc.) come with their own entry points that start a server automatically. + +Sometimes, though, it can be useful to start Jupyter Server directly when you want to run multiple Jupyter Web applications at the same time. For more details, see the :ref:`Managing multiple extensions ` page. If these extensions are enabled, you can simple run the following: + +.. code-block:: bash + + > jupyter server + + [I 2020-03-20 15:48:20.903 ServerApp] Serving notebooks from local directory: /Users/username/home + [I 2020-03-20 15:48:20.903 ServerApp] Jupyter Server 1.0.0 is running at: + [I 2020-03-20 15:48:20.903 ServerApp] http://localhost:8888/?token=<...> + [I 2020-03-20 15:48:20.903 ServerApp] or http://127.0.0.1:8888/?token=<...> + [I 2020-03-20 15:48:20.903 ServerApp] Use Control-C to stop this server and shut down all kernels (twice to skip confirmation). + [I 2020-03-20 15:48:20.903 ServerApp] Welcome to Project Jupyter! Explore the various tools available and their corresponding documentation. If you are interested in contributing to the platform, please visit the communityresources section at https://jupyter.org/community.html. + [C 2020-03-20 15:48:20.907 ServerApp] + + To access the server, open this file in a browser: + file:///Users/username/jpserver-###-open.html + Or copy and paste one of these URLs: + http://localhost:8888/?token=<...> + or http://127.0.0.1:8888/?token=<...> \ No newline at end of file