Merge pull request #134 from RRosio/docs

Updating documentation for nbclassic

Author: echarles

CONTRIBUTING.rst

@@ -43,7 +43,7 @@ You can also use the installer from the `Node.js website <https://nodejs.org>`_.
 
 
 Installing the Jupyter NbClassic
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once you have installed the dependencies mentioned above, use the following
 steps::
@@ -71,7 +71,7 @@ If you are working in development mode, you will see that your version of Jupyte
 Troubleshooting the Installation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you do not see that your Jupyter NbClassic is not running on dev mode, it's possible that you are
+If you do not see that your Jupyter NbClassic is running on dev mode, it's possible that you are
 running other instances of Jupyter NbClassic. You can try the following steps:
 
 1. Uninstall all instances of the NbClassic package. These include any installations you made using

docs/source/conf.py

@@ -93,7 +93,7 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'Jupyter Notebook'
+project = 'Jupyter NbClassic'
 copyright = '2015, Jupyter Team, https://jupyter.org'
 author = 'The Jupyter Team'
 

docs/source/config_overview.rst

@@ -3,13 +3,19 @@
 Configuration Overview
 ======================
 
+As NbClassic is a Jupyter Server Extension that is intended as an intermediary project while users
+migrate from Notebook 6 to Notebook 7, this document makes references to configuration
+files carried over from the classic Jupyter Notebook which will be executed when running
+nbclassic. For more general documentation regarding the Jupyter Server that NbClassic
+uses please visit the `Jupyter Server documentation <https://jupyter-server.readthedocs.io/en/latest/index.html>`_.
+
 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 Notebook:
+when using Jupyter NbClassic:
 
     - :ref:`Jupyter's common configuration system <configure_common>`
-    - :ref:`Notebook server <configure_nbserver>`
-    - :ref:`Notebook front-end client <configure_nbclient>`
+    - :ref:`NbClassic server <configure_nbserver>`
+    - :ref:`NbClassic front-end client <configure_nbclient>`
     - :ref:`Notebook extensions <configure_nbextensions>`
 
 Let's look at highlights of each area.
@@ -30,30 +36,29 @@ and editing settings is similar for all the Jupyter applications.
 
 .. _configure_nbserver:
 
-Notebook server
----------------
-The Notebook server runs the language kernel and communicates with the
-front-end Notebook client (i.e. the familiar notebook interface).
+NbClassic Server
+----------------
+The NbClassic server runs the language kernel and communicates with the
+front-end NbClassic client (i.e. the familiar notebook interface).
 
-  - Configuring the Notebook server
+  - Configuring the NbClassic server
 
       To create a ``jupyter_notebook_config.py`` file in the ``.jupyter``
       directory, with all the defaults commented out, use the following
       command::
 
-            $ jupyter notebook --generate-config
-
-        :ref:`Command line arguments for configuration <config>` settings are
-        documented in the configuration file and the user documentation.
+            $ jupyter nbclassic --generate-config
 
+      :ref:`Command line arguments for configuration <config>` settings are documented in the configuration file and the user documentation.
+      
   - :ref:`Running a Notebook server <working_remotely>`
   - Related: `Configuring a language kernel <https://ipython.readthedocs.io/en/latest/install/kernel_install.html>`_
     to run in the Notebook server enables your server to run other languages, like R or Julia.
 
 .. _configure_nbclient:
 
-Notebook front-end client
--------------------------
+NbClassic front-end client
+--------------------------
 
 .. toctree::
    :maxdepth: 2

docs/source/development_faq.rst

@@ -7,4 +7,4 @@ Developer FAQ
 
 .. code-block:: bash
 
-    python -m pip install notebook --pre --upgrade
+    python -m pip install nbclassic --pre --upgrade

docs/source/frontend_config.rst

@@ -1,15 +1,15 @@
 .. _frontend_config:
 
-Configuring the notebook frontend
+Configuring the NbClassic frontend
 =================================
 
 .. note::
 
-    The ability to configure the notebook frontend UI and preferences is
+    The ability to configure the nbclassic frontend UI and preferences is
     still a work in progress.
 
 This document is a rough explanation on how you can persist some configuration
-options for the notebook JavaScript.
+options for the nbclassic JavaScript.
 
 There is no exhaustive list of all the configuration options as most options
 are passed down to other libraries, which means that non valid

docs/source/index.rst

@@ -1,14 +1,14 @@
-====================
-The Jupyter Notebook
-====================
+==================
+Jupyter NbClassic
+==================
 
-* `Installation <https://jupyter.readthedocs.io/en/latest/install.html>`_
-* `Starting the Notebook <https://jupyter.readthedocs.io/en/latest/running.html>`_
+:ref:`Getting Started <NbClassicUsage>`
 
 .. toctree::
    :maxdepth: 1
    :caption: User Documentation
 
+   nbclassic
    notebook
    ui_components
    examples/Notebook/examples_index.rst
@@ -33,6 +33,7 @@ The Jupyter Notebook
    :caption: Contributor Documentation
 
    contributing
+   nbclassic_dev_faq
    development_faq
 
 .. toctree::

docs/source/nbclassic.rst

@@ -0,0 +1,107 @@
+.. _htmlnotebook:
+
+Jupyter NbClassic
+====================
+
+Introduction
+------------
+
+The nbclassic package is the implementation of the classic Jupyter
+Notebook 6 as a Jupyter Server extension. As proposed in the accepted
+`Jupyter Enhancement Proposal #79`_ the development of this package
+is due to plans being carried out to create a Notebook 7, that is based on
+the modern JupyterLab code-base. 
+
+While Notebook 7 provides a user experience equivalent to that of the
+classic Notebook 6, the technology stack used is incompatible with
+that which many Jupyter Notebook users have developed their Jupyter
+Notebook extensions with. Users may find themselves in need of a
+way to continue using the Jupyter Notebook 6 tech-stack as they
+transition to using the Jupyter Notebook 7. The NbClassic package
+intends to address that need.
+
+.. _Jupyter Enhancement Proposal #79: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
+
+.. _NbClassicUsage:
+
+NbClassic Usage
+---------------
+
+Installation
+~~~~~~~~~~~~
+
+Installing from PyPI:
+``> pip install nbclassic``
+This will automatically enable the extension in Jupyter Server.
+
+Launch directly:
+``> jupyter nbclassic``
+
+Alternatively, you can run Jupyter Server and visit the `/tree` endpoint:
+``> jupyter server``
+
+Configuration
+~~~~~~~~~~~~~
+
+To create a ``jupyter_nbclassic_config.py`` file in the ``.jupyter`` directory you can use the following command::
+    
+    $ jupyter nbclassic --generate-config
+
+Options
+~~~~~~~
+
+You can view a list of the available options by typing::
+
+    $ jupyter nbclassic --help
+    
+
+NbClassic in the Jupyter Ecosystem
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Read more details about the changes currently taking place in the
+Jupyter Ecosystem in this `team-compass issue`_.
+
+You can install the nbclassic, notebook 7 and jupyterlab, all three of
+which will be providing different user interfaces that will be available
+on the same server.
+
+As nbclassic provides the static assets for notebook 6.5.x, while
+having both installed should cause no issues, the user interface provided
+by these two packages will be the same. These UIs would be available in
+different servers.
+
+When using nbclassic and notebook <= 6.4.x you can expect that these UIs
+will not be only presented at different servers but may also differ as
+potential changes to the nbclassic UI will not be reflected in Notebook
+versions <= 6.4.x.
+
+.. _team-compass issue: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000
+
+NbClassic Development
+---------------------
+
+`Nbclassic <https://github.com/jupyter/nbclassic>`_ is the package that holds the UI components of
+the classic Jupyter Notebook 6 and serves this UI through the server
+endpoints provided by Jupyter Server.
+
+*Jupyter Server Extensions*
+- `Authoring a basic server extension <https://jupyter-server.readthedocs.io/en/latest/developers/extensions.html>`_
+
+**The jupyter/notebook Repository**: The original `jupyter/notebook`_ GitHub 
+repository now holds the codebase for the new Jupyter Notebook (version 7).
+
+.. _jupyter/notebook: https://github.com/jupyter/notebook
+
+
+NbClassic Timeline
+------------------
+As proposed in the `JEP #79`_, the nbclassic
+package will continue to be supported with critical security fixes
+in the transition period as users move to using the more modern 
+Jupyter Notebook 7.
+
+**Porting Notebook 6 Extensions**: Work being done in parallel. 
+ou can find a helpful list of classical Notebook extensions and corresponding Jupyterlab extensions
+if available at the `Jupyterlab-contrib website <https://jupyterlab-contrib.github.io/migrate_from_classical.html>`_.
+
+
+.. _JEP #79: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html

docs/source/nbclassic_dev_faq.rst

@@ -0,0 +1,87 @@
+The Development of NbClassic
+============================
+
+Here you will find information about some especially noteworthy updates made in NbClassic, issues that have been reported 
+and common questions.
+
+
+Noteworthy Updates in NbClassic 
+--------------------------------
+
+- Entrypoints in NbClassic
+    - In NbClassic entrypoints have been renamed (`Rename duplicate entrypoints #138`_) to:
+
+        - ``jupyter-nbclassic-extension``
+        - ``jupyter nbclassic-serverextension``
+        - ``jupyter-nbclassic-bundlerextension``
+
+    - The decision to rename these entrypoints came about after some deliberation and consideration for user experience. When considering the confusion that having a more implicit handling of the entrypoints might pose, the concensus was that renaming the entrypoints would allow for more observability and it would help highlight some of the changes that are happening in the Jupyter ecosystem.  
+
+.. _`Rename duplicate entrypoints #138`: https://github.com/jupyter/nbclassic/pull/138
+
+
+- Providing backwards compatibility with the  `jupyter_notebook_config.py` file
+    - With the goal of allowing NbClassic to be installed along with Notebook 7, the release of NbClassic 0.4 included changing the project name from `notebook` to `nbclassic`. In changing the 'name' attribute to be `nbclassic`, the traitlet behavior changed and resulted in the configuration file which was previously named `jupyter_notebook_config`, to be named `jupyter_nbclassic_config`. However, this was updated to manually set the file name to `jupyter_notebook_config`. With this, the configuration file is picked up whether Notebook or NbClassic are installed. 
+
+- Endpoints in NbClassic
+    - NbClassic handlers have been updated to account for Notebook 7 being installed (`Handlers under nbclassic if notebook 7 is found`_). If so, the resources from nbclassic will be served under the ``/nbclassic/`` URL subpath, so as to not interfere  with those resources being served by Jupyter Notebook.
+
+.. _`Handlers under nbclassic if notebook 7 is found`: https://github.com/jupyter/nbclassic/pull/141
+
+NbClassic Developer FAQ
+-----------------------
+
+1. Where should I submit my issue?
+
+    The Jupyter Notebook 6.4.x will only be taking security fixes, you can follow
+    these guidelines to `report a vulnerability`_.
+
+    For Notebook 6.5.x, as it is intended to be end of life and will receive only
+    bug and security fixes, issues of this type in the frontend should be reported in
+    the `jupyter/nbclassic`_ repository, bug and security issues for the server can be
+    submitted in the `jupyter/notebook`_ repository. 
+
+    Generally, user interface issues dealing with the nbclassic package can be
+    submitted to the `jupyter/nbclassic`_ repository, while server issues can be
+    reported to the `jupyter_server/jupyter_server`_ repository.
+
+    Notebook 7.x issues would require closer consideration as they could be
+    reported in the `jupyter/notebook`_, `jupyterlab/jupyterlab`_, or
+    `jupyter_server/jupyter_server`_ repositories depending on the issue.
+
+    .. _`report a vulnerability`: https://github.com/jupyter/security/blob/main/docs/vulnerability-handling.md#reporting-vulnerabilities
+    .. _`jupyter/nbclassic`: https://github.com/jupyter/nbclassic
+    .. _`jupyter/notebook`: https://github.com/jupyter/notebook
+    .. _`jupyter_server/jupyter_server`: https://github.com/jupyter-server/jupyter_server
+    .. _`jupyterlab/jupyterlab`: https://github.com/jupyterlab/jupyterlab
+
+    The Jupyter Community appreciates your efforts in making sure your issue is submitted to the correct project.
+    There are many projects within the Jupyter ecosystem which can mean some issues are best suited for repositories
+    different than those in which they may have been opened. In the case that the issue belongs in a different
+    repository, we can use the `MeeseeksDev bot`_ to move the issue to the appropriate repository so long as the
+    target repository is included in the `allowed organization list`_ in the MeeseeksDev codebase. You can see a
+    list of the Github links to Jupyter organizations, and the different Jupyter projects under each, in the
+    `Jupyter Community`_ page.
+
+    .. _`MeeseeksDev bot`: https://github.com/MeeseeksBox/MeeseeksDev#meeseeksdev-migrate-to-target-orgrepo
+    .. _`allowed organization list`: https://github.com/MeeseeksBox/MeeseeksDev/blob/master/meeseeksdev/__init__.py#L26
+    .. _`Jupyter Community`: https://jupyter.org/community
+
+
+Known issues
+------------
+
+Bellow are some known bugs and issues with the NbClassic project. These are items that may be of particular interest to users
+migrating from notebook to nbclassic.
+
+1. `#140 Error using jupyter_nbextensions_configurator with nbclassic <https://github.com/jupyter/nbclassic/issues/140>`_ is a 
+known issue with partial fix `Support nbclassic while updating the static path <https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator/pull/141>`_ 
+pending to be merged into the `Jupyter-contrib/jupyter_nbextensions_configurator <https://github.com/Jupyter-contrib/jupyter_nbextensions_configurator>`_ repository.
+
+    Once a release with this fix is available, users will be able to activate the extension with the following commands::
+
+    $ pip install jupyter_nbextensions_configurator
+    $ jupyter nbextension install --sys-prefix --py jupyter_nbextensions_configurator --overwrite
+    $ jupyter nbextension enable --sys-prefix --py jupyter_nbextensions_configurator
+    $ jupyter serverextension install --sys-prefix --py jupyter_nbextensions_configurator --overwrite
+    $ jupyter serverextension enable --sys-prefix --py jupyter_nbextensions_configurator