-
Notifications
You must be signed in to change notification settings - Fork 62
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Updating documentation for nbclassic #134
Merged
Merged
Changes from all commits
Commits
Show all changes
25 commits
Select commit
Hold shift + click to select a range
64991bd
updated contributing doc
RRosio bc748b8
Set up for nbclassic docs
RRosio 67dd443
nbclassic rst should be displayed at homepage
RRosio 591ab96
outine structure for nbclassic docs
RRosio 68129ea
Updates to nbclassic usage and installation documentation
RRosio bcad40c
Adding nbclassic development faq
RRosio 48d2cf8
Apply suggestions from code review
RRosio ee1a812
Add reference to team-compass issue detailing plans for nbclassic and…
RRosio de9f739
FAQ answer with information on where to submit issues
RRosio 83769ac
Update docs/source/nbclassic.rst
RRosio 445d4c7
update docs with nbclassic development section
RRosio ca50c81
reorder sections and add a section for known issues
RRosio 3367d2e
update naming convention from notebook v6 or v7 to notebook 6 or 7
RRosio 7cef969
update home page with nbclassic internal link and move notebook exter…
RRosio 3d31208
fix link indentation
RRosio ece7b23
add some additional config sections to nbclassic docs
RRosio d1db94c
removing local reference to nbclassic usage
RRosio c80a640
add getting started link to usage documentation and restore previous …
RRosio 4946e6f
revert change that coincided with downstream test fail
RRosio ee201ac
fix broken link and reformat referrence
RRosio 01a8e86
updating notebook referrences to nbclassic
RRosio 50f968c
update reference of NotebookApp to ServerApp
RRosio f025f1b
updating references from notebook to nbclassic
RRosio 6418b92
moving notice about jupyter server documentation
RRosio 65803c7
update config overview and Notebook's known issues in public server
RRosio File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe refer to jupyter/notebook-team-compass#5 (comment)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Okay awesome! Thank you for the link, I will add it to the documentation too!