rearrage some developer docs

Zsailer · Zsailer · commit 36eb1abf4f96 · 2020-03-24T15:39:03.000-07:00
diff --git 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
---------------------------
+==========================
 
 To build the documentation you'll need `Sphinx <http://www.sphinx-doc.org/en/master/>`_,
 `pandoc <https://pandoc.org/>`_ and a few other packages.
diff --git a/README.md b/README.md
@@ -4,17 +4,9 @@
 [![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 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.**
-
-Read more on the Jupyter Server [roadmap](https://github.com/jupyter/jupyter_server/issues/127).
-
-## Installation
+## Installation and Basic usage
 
 You can find the installation documentation for the
 [Jupyter platform, on ReadTheDocs](https://jupyter.readthedocs.io/en/latest/install.html).
@@ -26,34 +18,10 @@ To install the latest release locally, make sure you have
 
     $ pip install jupyter_server
 
-### Versioning and Branches
-
-If Jupyter Server is a dependency of your project/application, it is important that you pin it to a version that works for your application. Currently, Jupyter Server only has minor and patch versions. Different minor versions likely include API-changes while patch versions do not change API.
-
-When a new minor 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 minor version number. That way, the master branch always reflects the latest un-released version.
-
-To see the changes between releases, checkout the [CHANGELOG](https://github.com/jupyter/jupyter_server/blob/master/CHANGELOG.md).
-
-To install the latest patch of a given version:
-
-    $ pip install jupyter_server>=0.2
-
-## Usage - Running Jupyter Server
-
-### Running in a local installation
-
-Launch with:
+Launch Jupyter Server by calling:
 
     $ 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).
diff --git a/docs/source/contributors/contributing.rst b/docs/source/contributors/contributing.rst
@@ -1,3 +1,3 @@
 .. highlight:: sh
 
-.. include:: ../../CONTRIBUTING.rst
+.. include:: ../../../CONTRIBUTING.rst
diff --git a/docs/source/developers/basic-extension.rst b/docs/source/developers/basic-extension.rst
diff --git a/docs/source/developers/configurable-extension.rst b/docs/source/developers/configurable-extension.rst
@@ -1,17 +1,12 @@
-Creating a Jupyter Server Frontend
-==================================
+Creating a configurable, Jupyter Server extension
+=================================================
 
-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.
+Jupyter Server offers a base class, ``ExtensionApp``, for authoring configurable Jupyter Server extensions. This class handles most of the boilerplate code for setting up config, CLI, and registration with Jupyter Server.
 
-.. note::  This documentation is written for experienced developers.
+Writing an extension application
+--------------------------------
 
-
-.. _frontend:
-
-Writing a frontend application
-------------------------------
-
-Jupyter Server provides two key classes for writing a server frontend:
+Jupyter Server provides two key classes for writing a server extension:
 
     - ``ExtensionApp``
     - ``ExtensionHandlerMixin``
@@ -20,11 +15,11 @@ The ExtensionApp:
 
     - can have traits.
     - is configurable (from file or CLI)
-    - creates a namespace for the frontend's static files under ``/static/<extension_name>/``.
+    - creates a namespace for a extension's static files under ``/static/<extension_name>/``.
     - 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:
+To create a new Jupyter extension application, subclass the ``ExtensionApp`` like the example below:
 
 .. code-block:: python
 
@@ -63,7 +58,7 @@ To create a new Jupyter frontend application, subclass the ``ExtensionApp`` like
             # 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:
+The ``ExtensionApp`` uses the following methods and properties to connect your extension to the Jupyter server. Overwrite these pieces to add your custom settings, handlers and templates:
 
 Methods
 
@@ -78,10 +73,10 @@ Properties
 * ``load_other_extensions``: should your extension expose other server extensions when launched directly?
 
 
-Writing frontend handlers
--------------------------
+Writing handlers for an extension
+---------------------------------
 
-To write handlers for an ``ExtensionApp``, use the ``ExtensionHandlerMixin`` class. This class routes Tornado's ``static_url`` attribute to the ``/static/<extension_name>/`` namespace where your frontend's static files will be served.
+To write handlers for an ``ExtensionApp``, use the ``ExtensionHandlerMixin`` and ``JupyterHandler`` classes. The former class routes Tornado's ``static_url`` attribute to the ``/static/<extension_name>/`` namespace where your extension's static files will be served. The latter class provides Jupyter Server's auth methods and other handler settings.
 
 .. code-block:: python
 
diff --git a/docs/source/developers/dependency.rst b/docs/source/developers/dependency.rst
@@ -0,0 +1,19 @@
+Jupyter Server as a dependency
+==============================
+
+If your project depends directly on Jupyter Server, be sure to watch Jupyter Server's changelog_ 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 [CHANGELOG](https://github.com/jupyter/jupyter_server/blob/master/CHANGELOG.md).
+
+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:
+
+    > pip install jupyter_server==1.0
diff --git a/docs/source/developers/rest-api.rst b/docs/source/developers/rest-api.rst
@@ -0,0 +1 @@
+Jupyter Server's REST API
diff --git a/docs/source/extension-authors/dependency.rst b/docs/source/extension-authors/dependency.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -42,23 +42,30 @@ The Jupyter Server is a highly technical piece of the Jupyter Stack. Since most
    operators/security
 
 .. toctree::
-   :caption: Extension Authors
+   :caption: Developers
    :maxdepth: 1
-   :name: extension-authors
+   :name: developers
 
-   extension-authors/dependency
-   extension-authors/frontends
+   developers/dependency
+   developers/frontends
+   developers/rest-api
 
+.. toctree::
+   :caption: Contributors
+   :maxdepth: 1
+   :name: contributors
+
+   contributors/contributing
 
 
-- Depending on Jupyter Server
-- Migrating a Notebook server extension to Jupyter Server
-- Writing a basic server extension from scratch
-- Writing a frontend server extension from scratch
+.. - Depending on Jupyter Server
+.. - Migrating a Notebook server extension to Jupyter Server
+.. - Writing a basic server extension from scratch
+.. - Writing a frontend server extension from scratch
 
 
-Contributors
-~~~~~~~~~~~~
+.. Contributors
+.. ~~~~~~~~~~~~
 
-- Monthly Meetings and Roadmap
-- Changelog
+.. - Monthly Meetings and Roadmap
+.. - Changelog
diff --git a/docs/source/operators/configuring-extensions.rst b/docs/source/operators/configuring-extensions.rst
@@ -37,7 +37,7 @@ In Python config files, each trait will be prefixed with ``c.`` that links the t
     c.NotebookApp.port = 9999
 
 
-A Jupyter Server can automatically load config for multiple enabled extensions.
+A Jupyter Server will automatically load config for each enabled extension. You can config each extension by creating a jupyter config file for each extension.
 
 
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`.. highlight:: sh`
`2`	`2`
`3`		`-.. include:: ../../CONTRIBUTING.rst`
	`3`	`+.. include:: ../../../CONTRIBUTING.rst`
Original file line number	Diff line number	Diff line change
@@ -37,7 +37,7 @@ In Python config files, each trait will be prefixed with ``c.`` that links the t
`37`	`37`	`c.NotebookApp.port = 9999`
`38`	`38`
`39`	`39`
`40`		`-A Jupyter Server can automatically load config for multiple enabled extensions.`
	`40`	`+A Jupyter Server will automatically load config for each enabled extension. You can config each extension by creating a jupyter config file for each extension.`
`41`	`41`
`42`	`42`
`43`	`43`