-
Notifications
You must be signed in to change notification settings - Fork 62
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #134 from RRosio/docs
Updating documentation for nbclassic
- Loading branch information
Showing
13 changed files
with
312 additions
and
106 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.