diff --git a/.travis.yml b/.travis.yml index 1e0247f472..8658042ecf 100644 --- a/.travis.yml +++ b/.travis.yml @@ -54,7 +54,6 @@ script: make -C docs/ linkcheck || EXIT_STATUS=$?; fi - pytest --nbval --current-env docs || EXIT_STATUS=$? exit $EXIT_STATUS fi diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 13dcfd81db..49a54f2926 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -74,8 +74,8 @@ If you want coverage statistics as well, you can run:: Building the Documentation -------------------------- -To build the documentation you'll need `Sphinx `_, -`pandoc `_ and a few other packages. +To build the documentation you'll need `Sphinx `_, +`pandoc `_ and a few other packages. To install (and activate) a `conda environment`_ named ``server_docs`` containing all the necessary packages (except pandoc), use:: @@ -85,7 +85,7 @@ containing all the necessary packages (except pandoc), use:: activate notebook_docs # Windows .. _conda environment: - https://conda.io/docs/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file + https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file If you want to install the necessary packages with ``pip`` instead:: diff --git a/docs-translations/ko-KR/HowtoRun.md b/docs-translations/ko-KR/HowtoRun.md deleted file mode 100644 index eb070dea53..0000000000 --- a/docs-translations/ko-KR/HowtoRun.md +++ /dev/null @@ -1,57 +0,0 @@ -# Notebook 실행하기 - - ## 첫 걸음 - 1. 다음 명령어를 통해 Notebook 서버를 시작하세요 : - - $ jupyter notebook - - 2. 브라우저에 Notebook이 실행된 것을 확인할 수 있습니다. - - -# Notebook 서버 시작하기 - - Notebook을 컴퓨터에 설치하였으면 Notebook 서버를 시작할 수 있습니다. 다음 명령어를 이용하여 Notebook서버를 시작할 수 있습니다. - - $ jupyter notebook - - 이 명령어를 실행하면, 터미널에 웹 응용프로그램의 주소와 서버에 대한 정보가 출력됩니다. - - $ jupyter notebook - $ [I 08:58:24.417 NotebookApp] Serving notebooks from local directory: /Users/catherline - $ [I 08:58:24.417 NotebookApp] 0 active kernels - $ [I 08:58:24.417 NotebookApp] The Jupyter Notebook is running at: http://localhost:8888/ - $ [I 08:58:24.417 NotebookApp] Use Control-C to stop this server and shut down all kernels - - 기본 브라우저를 통해 이 주소가 열립니다. - - Notebook이 브라우저에 열리면, Notebook의 목록을 보여주는 Notebook Dashboard를 볼 수 있습니다. 대체로 가장 상위의 디렉토리를 열어줄 것입니다. - - **Notebook Dashboard** - -![Notebook Dashboard example](resources/dashboard.GIF "Notebook Dashboard") - -# Notebook 서버의 명령어 소개 - - ## 커스텀 IP 나 포트를 이용하여 시작하려면 어떻게 해야할까? - - 기본값으로, Notebook 서버는 포트 8888로 시작됩니다. 만약 포트8888이 사용할 수 없다면, Notebook 서버는 다른 가능한 포트를 찾습니다. 또한 임의로 포트를 설정해주는 것도 가능합니다. 예를 들어 포트 9999로 실행하면 : - - $ jupyter notebook --port 9999 - - - ## 브라우저를 열지않고 Notebook를 열기 - - 브라우저를 열지 않고 Notebook 서버를 시작하려면 : - - $ jupyter notebook --no-browser - - - ## Notebook 서버 옵션 도움말 보기 - - Notebook 서버는 --help 옵션을 통해 도움말 메시지를 제공합니다 : - - $ jupyter notebook --help - - - - diff --git a/docs-translations/ko-KR/Installation.md b/docs-translations/ko-KR/Installation.md deleted file mode 100644 index d5375d3b5e..0000000000 --- a/docs-translations/ko-KR/Installation.md +++ /dev/null @@ -1,33 +0,0 @@ -# Jupyter Notebook 설치하기 - -## 필요한 것 : Python - -Jupyter Notebook 을 설치하기 위해선 Jupyter가 많은 프로그래밍 언어들로 동작되기 때문에, Python이 필요합니다. (Python 3.3이상, Python 2.7) - -Python과 Jupyter를 설치할 때 Anaconda를 이용하는 것을 추천합니다. 밑에서 이를 이용하여 설치할 것입니다. - -## Anaconda 와 conda 를 이용하여 Jupyter 설치하기 - -새로운 이용자들은 Anaconda를 설치하는 것을 강력하게 추천합니다. Anaconda는 Python과 Jupyter를 쉽게 설치하게 해주고, 과학적인 계산과 데이터를 위한 자주 사용되는 패키지들의 설치에도 유용합니다. - -설치 순서 : - - 1. Anaconda를 다운받으세요. Anaconda의 가장 최신의 Python 3버전을 다운 받는 것을 추천합니다. - 2. 다운 받은 Anaconda 의 다운로드 페이지에 있는 설명을 읽고 설치해주세요. - 3. 축하합니다. Jupyter Notebook 을 설치하셨습니다. Jupyter Notebook을 실행하려면 : - - $ jupyter notebook - -## 숙련된 Python 이용자 : pip을 통해 설치하기 - - Python 이용자라면, Anaconda 대신에 Python의 패키지 매니저 pip을 이용하여 설치하세요. - - 첫째로, 가장 최신의 pip인지를 확인하세요; 구 버전은 독립성에 문제가 있을 수 있습니다. - - $ pip install --upgrade pip - - 이제 다음을 이용하여 Jupyter Notebook를 설치하세요 : - - $ pip install jupyter - - (축하합니다. Jupyter Notebook를 설치하셨습니다.) diff --git a/docs-translations/ko-KR/README.md b/docs-translations/ko-KR/README.md deleted file mode 100644 index 3e6f9aa69b..0000000000 --- a/docs-translations/ko-KR/README.md +++ /dev/null @@ -1,55 +0,0 @@ -# Jupyter Notebook - -[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter) -[![Build Status](https://travis-ci.org/jupyter/notebook.svg?branch=master)](https://travis-ci.org/jupyter/notebook) -[![Documentation Status](https://readthedocs.org/projects/jupyter-notebook/badge/?version=latest)](http://jupyter-notebook.readthedocs.io/en/latest/?badge=latest) - -English 버전 링크 : [[English Version](http://github.com/jupyter/notebook/)] - -Jupyter notebook 은 상호 교환을 위한 웹 기반 환경입니다. - -![Jupyter notebook example](resources/running_code_med.png "Jupyter notebook example") - -### Jupyter notebook, 사용자의 언어에 독립적인 IPython notebook의 진화 -Jupyter notebook은 Jupyter 프로젝트를 위한 사용자 언어에 독립적인 HTML 응용 프로그램입니다. -2015년에 Jupyter notebook은 IPython 코드 기반의 The Big Split™ 의 일부분으로 시작되었습니다. -IPython 3는 *IPython notebook* 과 같은 사용자 언어에 독립적인 코드와 *IPython kernel for Python* 과 같은 특정언어 기반의 코드의 기능을 가지고 출시되었습니다. -컴퓨터에는 많은 언어가 사용되기 때문에, Jupyter 프로젝트는 사용자 언어에 독립적인 **Jupyter notebook** 을 이 저장소와 개인의 독립적인 저장소에 있는 특정언어 중심의 커널의 도움으로 지속적으로 개발할 것입니다. -[[The Big Split™ announcement](https://blog.jupyter.org/2015/04/15/the-big-split/)] -[[Jupyter Ascending blog post](http://blog.jupyter.org/2015/08/12/first-release-of-jupyter/)] - -## 설치 -설치법 문서는 다음 주소에서 찾을 수 있습니다. -You can find the installation documentation for the -[Jupyter platform, on ReadTheDocs](https://jupyter.readthedocs.io/en/latest/install.html). -조금 더 심화된 Jupyter notebook의 사용은 다음 주소에서 볼 수 있습니다. -[here](https://jupyter-notebook.readthedocs.io/en/latest/). - -설치를 위해서는 -[pip installed](https://pip.readthedocs.io/en/stable/installing/) 가 있는지 확인한 후 다음을 실행해주세요: - - $ pip install notebook - -## 활용 - Jupyter notebook 실행하기 - -### 로컬에서 실행할 때 - -이와 같이 실행하세요: - - $ jupyter notebook - -## 개발 설치 - -[`CONTRIBUTING.rst`](CONTRIBUTING.rst) 을 통해 설치법을 확인하세요. - -## 기여하기 - -이 프로젝트에 기여를 하고 싶다면, [`CONTRIBUTING.rst`](CONTRIBUTING.rst) 을 참고해주세요. - -## 자료 -- [Project Jupyter website](https://jupyter.org) -- [Online Demo at try.jupyter.org](https://try.jupyter.org) -- [Documentation for Jupyter notebook](https://jupyter-notebook.readthedocs.io/en/latest/) [[PDF](https://media.readthedocs.org/pdf/jupyter-notebook/latest/jupyter-notebook.pdf)] -- [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/notebook/issues) -- [Technical support - Jupyter Google Group](https://groups.google.com/forum/#!forum/jupyter) diff --git a/docs-translations/ko-KR/UIComponents.md b/docs-translations/ko-KR/UIComponents.md deleted file mode 100644 index c582c7ead5..0000000000 --- a/docs-translations/ko-KR/UIComponents.md +++ /dev/null @@ -1,38 +0,0 @@ -# UI 기능 - -버그 리포트나 Jupyter Mailing list에 메일을 보내려고 할 때, 개발자나 사용자들이 버그를 진단하거나 해결해줄 경우 다른 UI를 사용하면 시간이 단축된다. -이번 장에서는 Notebook과 Notebook의 다른 모드의 UI 요소를 알려줄 것이다. - - ## Notebook Dashboard - -jupyter notebook 명령어를 실행하면 가장 먼저 Notebook Dashboard가 나타난다. - -![Notebook Dashboard example](resources/dashboard.GIF "Notebook Dashboard") - - - - ## Notebook 편집기 - -편집을 위해 Notebook을 선택했다면, Notebook은 Notebook편집기를 열어준다. - -![Notebook Editor example](resources/Notebook_Editor.GIF "Notebook Editor") - ## Notebook 의 사용자 도움 인터페이스 - -만약 Notebook 편집기의 특정 요소를 더 배우고 싶다면, 도움 메뉴 - 사용자 인터페이스 를 선택함으로써 사용사 인터페이스 도움말을 볼 수 있습니다. - - ## 편집 모드와 Notebook편집기 - -셀이 편집모드에 있다면, 셀 모드 지시자는 셀의 상태를 반영합니다. 이 상태는 오른쪽 위의 작은 연필모양으로 선택가능합니다. 셀이 명령 모드에 있다면, 그 위치에 아이콘이 없습니다. - -![Edit Mode example](resources/edit_mode.GIF "Edit Mode") - - ## 파일 편집기 - -이제 Notebook Dashboard 안의 Notebook 파일이 아닌 표시된 파일을 선택하여 열어야한다고 한다면, 파일은 파일 편집기로 열립니다. - -![File Editor example](resources/file_editor.GIF "File Editor") - - - - - diff --git a/docs-translations/ko-KR/resources/Notebook_Editor.GIF b/docs-translations/ko-KR/resources/Notebook_Editor.GIF deleted file mode 100644 index 50e433d41f..0000000000 Binary files a/docs-translations/ko-KR/resources/Notebook_Editor.GIF and /dev/null differ diff --git a/docs-translations/ko-KR/resources/dashboard.GIF b/docs-translations/ko-KR/resources/dashboard.GIF deleted file mode 100644 index e34f1d971b..0000000000 Binary files a/docs-translations/ko-KR/resources/dashboard.GIF and /dev/null differ diff --git a/docs-translations/ko-KR/resources/edit_mode.GIF b/docs-translations/ko-KR/resources/edit_mode.GIF deleted file mode 100644 index 6dd34d0171..0000000000 Binary files a/docs-translations/ko-KR/resources/edit_mode.GIF and /dev/null differ diff --git a/docs-translations/ko-KR/resources/file_editor.GIF b/docs-translations/ko-KR/resources/file_editor.GIF deleted file mode 100644 index 69595f37fa..0000000000 Binary files a/docs-translations/ko-KR/resources/file_editor.GIF and /dev/null differ diff --git a/docs-translations/ko-KR/resources/running_code_med.png b/docs-translations/ko-KR/resources/running_code_med.png deleted file mode 100644 index 6f80194745..0000000000 Binary files a/docs-translations/ko-KR/resources/running_code_med.png and /dev/null differ diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt index be3f353637..a99918f253 100644 --- a/docs/doc-requirements.txt +++ b/docs/doc-requirements.txt @@ -1,4 +1,3 @@ sphinx>=1.3.6 sphinx-rtd-theme -nbsphinx sphinxcontrib_github_alt diff --git a/docs/environment.yml b/docs/environment.yml index ca73057e88..23f013f6be 100644 --- a/docs/environment.yml +++ b/docs/environment.yml @@ -9,7 +9,6 @@ dependencies: - ipykernel - sphinx - pip: - - nbsphinx - Send2Trash - prometheus_client - sphinxcontrib_github_alt diff --git a/docs/jsdoc_config.json b/docs/jsdoc_config.json deleted file mode 100644 index 4da2e3d8b1..0000000000 --- a/docs/jsdoc_config.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "markdown": { - "parser": "gfm" - }, - "plugins": [ - "plugins/markdown" , - "jsdoc_plugin.js" - ], - "source": { - "include": [ - "../notebook/static/notebook/js/notebook.js" - ] - }, - "tags": { - "allowUnknownTags": true - }, - "templates": { - "cleverLinks": false, - "monospaceLinks": false - } -} diff --git a/docs/jsdoc_plugin.js b/docs/jsdoc_plugin.js deleted file mode 100644 index 3fa3035020..0000000000 --- a/docs/jsdoc_plugin.js +++ /dev/null @@ -1,12 +0,0 @@ -exports.handlers = { - newDoclet: function(e) { - // e.doclet will refer to the newly created doclet - // you can read and modify properties of that doclet if you wish - if (typeof e.doclet.name === 'string') { - if (e.doclet.name[0] == '_') { - console.log('Private method "' + e.doclet.longname + '" not documented.'); - e.doclet.memberof = ''; - } - } - } -}; \ No newline at end of file diff --git a/docs/resources/Info.plist.example b/docs/resources/Info.plist.example deleted file mode 100644 index bfdd89bf0b..0000000000 --- a/docs/resources/Info.plist.example +++ /dev/null @@ -1,20 +0,0 @@ - # Add this into the info.plist file of an application - # and the icns icon in Contents/Resources - # then move the application twice : - # https://superuser.com/questions/178316/how-to-set-an-icon-for-a-file-type-on-mac - - CFBundleDocumentTypes - - - CFBundleTypeExtensions - - ipynb - - CFBundleTypeIconFile - ipynb_mac_icon - CFBundleTypeName - IPython notebook file - CFBundleTypeRole - None - - diff --git a/docs/resources/generate_icons.sh b/docs/resources/generate_icons.sh deleted file mode 100755 index a72b2d867f..0000000000 --- a/docs/resources/generate_icons.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash -INKSCAPE=inkscape - -${INKSCAPE} -z -C --file=ipynb_icon_16x16.svg --export-png=ipynb_icon_16x16_uncrush.png -${INKSCAPE} -z -C --file=ipynb_icon_24x24.svg --export-png=ipynb_icon_24x24_uncrush.png -${INKSCAPE} -z -C --file=ipynb_icon_32x32.svg --export-png=ipynb_icon_32x32_uncrush.png -${INKSCAPE} -z -C --file=ipynb_icon_512x512.svg --export-png=ipynb_icon_64x64_uncrush.png -w 64 -h 64 -${INKSCAPE} -z -C --file=ipynb_icon_512x512.svg --export-png=ipynb_icon_128x128_uncrush.png -w 128 -h 128 -${INKSCAPE} -z -C --file=ipynb_icon_512x512.svg --export-png=ipynb_icon_256x256_uncrush.png -w 256 -h 256 -${INKSCAPE} -z -C --file=ipynb_icon_512x512.svg --export-png=ipynb_icon_512x512_uncrush.png -w 512 -h 512 - - -for file in `ls *_uncrush.png`; do - pngcrush -brute -l 9 -reduce -rem alla -rem text -rem time -rem gAMA -rem cHRM -rem iCCP -rem sRGB $file `basename $file _uncrush.png`.png - rm $file -done diff --git a/docs/resources/icon_16x16.svg b/docs/resources/icon_16x16.svg deleted file mode 100644 index 29145e80d0..0000000000 --- a/docs/resources/icon_16x16.svg +++ /dev/null @@ -1,149 +0,0 @@ - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/resources/icon_24x24.svg b/docs/resources/icon_24x24.svg deleted file mode 100644 index c50ef1f07d..0000000000 --- a/docs/resources/icon_24x24.svg +++ /dev/null @@ -1,167 +0,0 @@ - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/resources/icon_32x32.svg b/docs/resources/icon_32x32.svg deleted file mode 100644 index 7a19362269..0000000000 --- a/docs/resources/icon_32x32.svg +++ /dev/null @@ -1,311 +0,0 @@ - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Jupyter - diff --git a/docs/resources/icon_512x512.svg b/docs/resources/icon_512x512.svg deleted file mode 100644 index f7f0281664..0000000000 --- a/docs/resources/icon_512x512.svg +++ /dev/null @@ -1,226 +0,0 @@ - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Jupyter - - diff --git a/docs/resources/ipynb.icns b/docs/resources/ipynb.icns deleted file mode 100644 index 7f3898c650..0000000000 Binary files a/docs/resources/ipynb.icns and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_1024x1024.png b/docs/resources/ipynb.iconset/icon_1024x1024.png deleted file mode 100644 index b2c8f07dce..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_1024x1024.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_128x128.png b/docs/resources/ipynb.iconset/icon_128x128.png deleted file mode 100644 index 5e50eee511..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_128x128.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_128x128@2x.png b/docs/resources/ipynb.iconset/icon_128x128@2x.png deleted file mode 100644 index 3acf85895d..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_128x128@2x.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_16x16.png b/docs/resources/ipynb.iconset/icon_16x16.png deleted file mode 100644 index d2a5c7a4b9..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_16x16.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_16x16@2x.png b/docs/resources/ipynb.iconset/icon_16x16@2x.png deleted file mode 100644 index 46b7e1cb0f..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_16x16@2x.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_24x24.png b/docs/resources/ipynb.iconset/icon_24x24.png deleted file mode 100644 index caaa7853b6..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_24x24.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_24x24@2x.png b/docs/resources/ipynb.iconset/icon_24x24@2x.png deleted file mode 100644 index d35831ddaa..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_24x24@2x.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_256x256.png b/docs/resources/ipynb.iconset/icon_256x256.png deleted file mode 100644 index 3acf85895d..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_256x256.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_256x256@2x.png b/docs/resources/ipynb.iconset/icon_256x256@2x.png deleted file mode 100644 index 6b65de3e5d..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_256x256@2x.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_32x32.png b/docs/resources/ipynb.iconset/icon_32x32.png deleted file mode 100644 index a4dfcfd754..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_32x32.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_32x32@2x.png b/docs/resources/ipynb.iconset/icon_32x32@2x.png deleted file mode 100644 index cefed98e6a..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_32x32@2x.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_48x48.png b/docs/resources/ipynb.iconset/icon_48x48.png deleted file mode 100644 index 0f57dd0a2d..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_48x48.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_512x512.png b/docs/resources/ipynb.iconset/icon_512x512.png deleted file mode 100644 index 6b65de3e5d..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_512x512.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_512x512@2x.png b/docs/resources/ipynb.iconset/icon_512x512@2x.png deleted file mode 100644 index 83e165003a..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_512x512@2x.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_64x64.png b/docs/resources/ipynb.iconset/icon_64x64.png deleted file mode 100644 index e21b4575aa..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_64x64.png and /dev/null differ diff --git a/docs/resources/ipynb.iconset/icon_64x64@2x.png b/docs/resources/ipynb.iconset/icon_64x64@2x.png deleted file mode 100644 index 5e50eee511..0000000000 Binary files a/docs/resources/ipynb.iconset/icon_64x64@2x.png and /dev/null differ diff --git a/docs/resources/notebook_basics.png b/docs/resources/notebook_basics.png deleted file mode 100644 index d75ce11fea..0000000000 Binary files a/docs/resources/notebook_basics.png and /dev/null differ diff --git a/docs/resources/running_code.png b/docs/resources/running_code.png deleted file mode 100644 index c74ee403fd..0000000000 Binary files a/docs/resources/running_code.png and /dev/null differ diff --git a/docs/resources/running_code_med.png b/docs/resources/running_code_med.png deleted file mode 100644 index 6f80194745..0000000000 Binary files a/docs/resources/running_code_med.png and /dev/null differ diff --git a/docs/source/_static/images/blank-notebook-ui.png b/docs/source/_static/images/blank-notebook-ui.png deleted file mode 100644 index f497626368..0000000000 Binary files a/docs/source/_static/images/blank-notebook-ui.png and /dev/null differ diff --git a/docs/source/_static/images/blank-notebook-ui.svg b/docs/source/_static/images/blank-notebook-ui.svg deleted file mode 100644 index 10f5ab4fd0..0000000000 --- a/docs/source/_static/images/blank-notebook-ui.svg +++ /dev/null @@ -1,397 +0,0 @@ - - - - - - - - image/svg+xml - - - - - - - - - - - ⇦ Notebook name - - Menu bar - Toolbar - Code cell - diff --git a/docs/source/_static/images/cell-tags-toolbar.png b/docs/source/_static/images/cell-tags-toolbar.png deleted file mode 100644 index cab448f9ec..0000000000 Binary files a/docs/source/_static/images/cell-tags-toolbar.png and /dev/null differ diff --git a/docs/source/_static/images/cell-toolbar-41.png b/docs/source/_static/images/cell-toolbar-41.png deleted file mode 100644 index 8a93e64c4a..0000000000 Binary files a/docs/source/_static/images/cell-toolbar-41.png and /dev/null differ diff --git a/docs/source/_static/images/command-palette-41.png b/docs/source/_static/images/command-palette-41.png deleted file mode 100644 index 272f11fa17..0000000000 Binary files a/docs/source/_static/images/command-palette-41.png and /dev/null differ diff --git a/docs/source/_static/images/dashboard-sort.png b/docs/source/_static/images/dashboard-sort.png deleted file mode 100644 index 020cc04164..0000000000 Binary files a/docs/source/_static/images/dashboard-sort.png and /dev/null differ diff --git a/docs/source/_static/images/find-replace-41.png b/docs/source/_static/images/find-replace-41.png deleted file mode 100644 index 73e57a68e2..0000000000 Binary files a/docs/source/_static/images/find-replace-41.png and /dev/null differ diff --git a/docs/source/_static/images/jupyter-file-editor.png b/docs/source/_static/images/jupyter-file-editor.png deleted file mode 100644 index 1447ed8abe..0000000000 Binary files a/docs/source/_static/images/jupyter-file-editor.png and /dev/null differ diff --git a/docs/source/_static/images/jupyter-notebook-dashboard.png b/docs/source/_static/images/jupyter-notebook-dashboard.png deleted file mode 100644 index 812545ceb8..0000000000 Binary files a/docs/source/_static/images/jupyter-notebook-dashboard.png and /dev/null differ diff --git a/docs/source/_static/images/jupyter-notebook-default.png b/docs/source/_static/images/jupyter-notebook-default.png deleted file mode 100644 index aa904475f9..0000000000 Binary files a/docs/source/_static/images/jupyter-notebook-default.png and /dev/null differ diff --git a/docs/source/_static/images/jupyter-notebook-edit.png b/docs/source/_static/images/jupyter-notebook-edit.png deleted file mode 100644 index 81e0fcaf11..0000000000 Binary files a/docs/source/_static/images/jupyter-notebook-edit.png and /dev/null differ diff --git a/docs/source/_static/images/jupyter-verification.png b/docs/source/_static/images/jupyter-verification.png deleted file mode 100644 index da816450e5..0000000000 Binary files a/docs/source/_static/images/jupyter-verification.png and /dev/null differ diff --git a/docs/source/_static/images/multi-select-41.png b/docs/source/_static/images/multi-select-41.png deleted file mode 100644 index 3c8cd51a0c..0000000000 Binary files a/docs/source/_static/images/multi-select-41.png and /dev/null differ diff --git a/docs/source/_static/images/new-notebook.gif b/docs/source/_static/images/new-notebook.gif deleted file mode 100644 index 2db70c14f8..0000000000 Binary files a/docs/source/_static/images/new-notebook.gif and /dev/null differ diff --git a/docs/source/_static/images/shortcut-editor.png b/docs/source/_static/images/shortcut-editor.png deleted file mode 100644 index efe5fce681..0000000000 Binary files a/docs/source/_static/images/shortcut-editor.png and /dev/null differ diff --git a/docs/source/_static/images/table-style-after.png b/docs/source/_static/images/table-style-after.png deleted file mode 100644 index dadbed4531..0000000000 Binary files a/docs/source/_static/images/table-style-after.png and /dev/null differ diff --git a/docs/source/_static/images/table-style-before.png b/docs/source/_static/images/table-style-before.png deleted file mode 100644 index 1f4d976b24..0000000000 Binary files a/docs/source/_static/images/table-style-before.png and /dev/null differ diff --git a/docs/source/comms.rst b/docs/source/comms.rst deleted file mode 100644 index 1a0a5a3250..0000000000 --- a/docs/source/comms.rst +++ /dev/null @@ -1,98 +0,0 @@ -Comms -===== - -*Comms* allow custom messages between the frontend and the kernel. They are used, -for instance, in `ipywidgets `__ to -update widget state. - -A comm consists of a pair of objects, in the kernel and the frontend, with an -automatically assigned unique ID. When one side sends a message, a callback on -the other side is triggered with that message data. Either side, the frontend -or kernel, can open or close the comm. - -.. seealso:: - - `Custom Messages `__ - The messaging specification section on comms - -Opening a comm from the kernel ------------------------------- - -First, the function to accept the comm must be available on the frontend. This -can either be specified in a `requirejs` module, or registered in a registry, for -example when an :doc:`extension ` is loaded. -This example shows a frontend comm target registered in a registry: - -.. code-block:: javascript - - Jupyter.notebook.kernel.comm_manager.register_target('my_comm_target', - function(comm, msg) { - // comm is the frontend comm instance - // msg is the comm_open message, which can carry data - - // Register handlers for later messages: - comm.on_msg(function(msg) {...}); - comm.on_close(function(msg) {...}); - comm.send({'foo': 0}); - }); - -Now that the frontend comm is registered, you can open the comm from the kernel: - -.. code-block:: python - - from ipykernel.comm import Comm - - # Use comm to send a message from the kernel - my_comm = Comm(target_name='my_comm_target', data={'foo': 1}) - my_comm.send({'foo': 2}) - - # Add a callback for received messages. - @my_comm.on_msg - def _recv(msg): - # Use msg['content']['data'] for the data in the message - - -This example uses the IPython kernel; it's up to each language kernel what API, -if any, it offers for using comms. - -Opening a comm from the frontend --------------------------------- - -This is very similar to above, but in reverse. First, a comm target must be -registered in the kernel. For instance, this may be done by code displaying -output: it will register a target in the kernel, and then display output -containing Javascript to connect to it. - -.. code-block:: python - - def target_func(comm, msg): - # comm is the kernel Comm instance - # msg is the comm_open message - - # Register handler for later messages - @comm.on_msg - def _recv(msg): - # Use msg['content']['data'] for the data in the message - - # Send data to the frontend - comm.send({'foo': 5}) - - get_ipython().kernel.comm_manager.register_target('my_comm_target', target_func) - -This example uses the IPython kernel again; this example will be different in -other kernels that support comms. Refer to the specific language kernel's -documentation for comms support. - -And then open the comm from the frontend: - -.. code-block:: javascript - - comm = Jupyter.notebook.kernel.comm_manager.new_comm('my_comm_target', - {'foo': 6}) - // Send data - comm.send({'foo': 7}) - - // Register a handler - comm.on_msg(function(msg) { - console.log(msg.content.data.foo); - }); diff --git a/docs/source/conf.py b/docs/source/conf.py index 04c6b1a9b7..d0f5478647 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -69,7 +69,6 @@ 'sphinx.ext.autosummary', 'sphinx.ext.mathjax', 'IPython.sphinxext.ipython_console_highlighting', - 'nbsphinx', 'sphinxcontrib_github_alt', ] @@ -140,7 +139,8 @@ #show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'default' +#highlight_language = 'python3' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] diff --git a/docs/source/config_overview.rst b/docs/source/config_overview.rst index e9364d7af9..ee49b766cd 100644 --- a/docs/source/config_overview.rst +++ b/docs/source/config_overview.rst @@ -30,11 +30,10 @@ and editing settings is similar for all the Jupyter applications. .. _configure_server: -Jupyter server --------------- +Server-specific configuration +----------------------------- -The Jupyter server runs the language kernel and communicates with the -front-end client (i.e. JupyterLab). +The Jupyter server runs the language kernel and communicates with Jupyter Server frontends. - Configuring the Jupyter server @@ -56,10 +55,9 @@ front-end client (i.e. JupyterLab). Server extensions ----------------- -- `Distributing Jupyter Extensions as Python Packages `_ - `Extending the Server `_ -:ref:`Security in Jupyter: ` Since security +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 diff --git a/docs/source/development_faq.rst b/docs/source/development_faq.rst deleted file mode 100644 index 562d7fde8d..0000000000 --- a/docs/source/development_faq.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _development_faq: - -Developer FAQ -============= - -1. How do I install a prerelease version such as a beta or release candidate? - -.. code-block:: bash - - python -m pip install notebook --pre --upgrade diff --git a/docs/source/development_release.rst b/docs/source/development_release.rst deleted file mode 100644 index 4350ace10f..0000000000 --- a/docs/source/development_release.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. _notebook_release: - -Making a Notebook release -========================= - -This document guides a contributor through creating a release of the Jupyter -notebook. - -Check installed tools ---------------------- - -Review ``CONTRIBUTING.rst``. Make sure all the tools needed to generate the -minified JavaScript and CSS files are properly installed. - -Clean the repository --------------------- - -You can remove all non-tracked files with: - -.. code:: bash - - git clean -xfdi - -This would ask you for confirmation before removing all untracked files. Make -sure the ``dist/`` folder is clean and avoid stale build from -previous attempts. - -Create the release ------------------- - -#. Update version number in ``notebook/_version.py``. - -#. Run this command: - - .. code:: bash - - python setup.py jsversion - - It will modify (at least) ``notebook/static/base/js/namespace.js`` which - makes the notebook version available from within JavaScript. - -#. Commit and tag the release with the current version number: - - .. code:: bash - - git commit -am "release $VERSION" - git tag $VERSION - -#. You are now ready to build the ``sdist`` and ``wheel``: - - .. code:: bash - - python setup.py sdist - python setup.py bdist_wheel - -#. You can now test the ``wheel`` and the ``sdist`` locally before uploading - to PyPI. Make sure to use `twine `_ to - upload the archives over SSL. - - .. code:: bash - - twine upload dist/* - -#. If all went well, change the ``notebook/_version.py`` back adding the - ``.dev`` suffix. - -#. Push directly on master, not forgetting to push ``--tags`` too. diff --git a/docs/source/examples/Notebook/Connecting with the Qt Console.ipynb b/docs/source/examples/Notebook/Connecting with the Qt Console.ipynb deleted file mode 100644 index 4794200413..0000000000 --- a/docs/source/examples/Notebook/Connecting with the Qt Console.ipynb +++ /dev/null @@ -1,130 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Connecting to an existing IPython kernel using the Qt Console" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The Frontend/Kernel Model" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The traditional IPython (`ipython`) consists of a single process that combines a terminal based UI with the process that runs the users code.\n", - "\n", - "While this traditional application still exists, the modern Jupyter consists of two processes:\n", - "\n", - "* Kernel: this is the process that runs the users code.\n", - "* Frontend: this is the process that provides the user interface where the user types code and sees results.\n", - "\n", - "Jupyter currently has 3 frontends:\n", - "\n", - "* Terminal Console (`jupyter console`)\n", - "* Qt Console (`jupyter qtconsole`)\n", - "* Notebook (`jupyter notebook`)\n", - "\n", - "The Kernel and Frontend communicate over a ZeroMQ/JSON based messaging protocol, which allows multiple Frontends (even of different types) to communicate with a single Kernel. This opens the door for all sorts of interesting things, such as connecting a Console or Qt Console to a Notebook's Kernel. For example, you may want to connect a Qt console to your Notebook's Kernel and use it as a help\n", - "browser, calling `??` on objects in the Qt console (whose pager is more flexible than the\n", - "one in the notebook). \n", - "\n", - "This Notebook describes how you would connect another Frontend to an IPython Kernel that is associated with a Notebook.\n", - "The commands currently given here are specific to the IPython kernel." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Manual connection" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "To connect another Frontend to a Kernel manually, you first need to find out the connection information for the Kernel using the `%connect_info` magic:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "%connect_info" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You can see that this magic displays everything you need to connect to this Notebook's Kernel." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Automatic connection using a new Qt Console" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "You can also start a new Qt Console connected to your current Kernel by using the `%qtconsole` magic. This will detect the necessary connection\n", - "information and start the Qt Console for you automatically." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "a = 10" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "%qtconsole" - ] - } - ], - "metadata": { - "nbsphinx": { - "execute": "never" - }, - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.5.2" - } - }, - "nbformat": 4, - "nbformat_minor": 1 -} diff --git a/docs/source/examples/Notebook/Custom Keyboard Shortcuts.ipynb b/docs/source/examples/Notebook/Custom Keyboard Shortcuts.ipynb deleted file mode 100644 index 64576268d2..0000000000 --- a/docs/source/examples/Notebook/Custom Keyboard Shortcuts.ipynb +++ /dev/null @@ -1,157 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Keyboard Shortcut Customization" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Starting with Jupyter Notebook 5.0, you can customize the `command` mode shortcuts from within the Notebook Application itself. \n", - "\n", - "Head to the **`Help`** menu and select the **`Edit keyboard Shortcuts`** item.\n", - "A dialog will guide you through the process of adding custom keyboard shortcuts.\n", - "\n", - "Keyboard shortcut set from within the Notebook Application will be persisted to your configuration file. \n", - "A single action may have several shortcuts attached to it." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Keyboard Shortcut Customization (Pre Notebook 5.0)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Starting with IPython 2.0 keyboard shortcuts in command and edit mode are fully customizable. These customizations are made using the Jupyter JavaScript API. Here is an example that makes the `r` key available for running a cell:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "%%javascript\n", - "\n", - "Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', {\n", - " help : 'run cell',\n", - " help_index : 'zz',\n", - " handler : function (event) {\n", - " IPython.notebook.execute_cell();\n", - " return false;\n", - " }}\n", - ");" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "\"By default the keypress `r`, while in command mode, changes the type of the selected cell to `raw`. This shortcut is overridden by the code in the previous cell, and thus the action no longer be available via the keypress `r`.\"" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "There are a couple of points to mention about this API:\n", - "\n", - "* The `help_index` field is used to sort the shortcuts in the Keyboard Shortcuts help dialog. It defaults to `zz`.\n", - "* When a handler returns `false` it indicates that the event should stop propagating and the default action should not be performed. For further details about the `event` object or event handling, see the jQuery docs.\n", - "* If you don't need a `help` or `help_index` field, you can simply pass a function as the second argument to `add_shortcut`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "%%javascript\n", - "\n", - "Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', function (event) {\n", - " IPython.notebook.execute_cell();\n", - " return false;\n", - "});" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Likewise, to remove a shortcut, use `remove_shortcut`:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "%%javascript\n", - "\n", - "Jupyter.keyboard_manager.command_shortcuts.remove_shortcut('r');" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "If you want your keyboard shortcuts to be active for all of your notebooks, put the above API calls into your `custom.js` file." - ] - }, - { - "cell_type": "markdown", - "metadata": { - "collapsed": true - }, - "source": [ - "Of course we provide name for majority of existing action so that you do not have to re-write everything, here is for example how to bind `r` back to it's initial behavior:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "%%javascript\n", - "\n", - "Jupyter.keyboard_manager.command_shortcuts.add_shortcut('r', 'jupyter-notebook:change-cell-to-raw');" - ] - } - ], - "metadata": { - "nbsphinx": { - "execute": "never" - }, - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.5.2" - } - }, - "nbformat": 4, - "nbformat_minor": 1 -} diff --git a/docs/source/examples/Notebook/Distributing Jupyter Extensions as Python Packages.ipynb b/docs/source/examples/Notebook/Distributing Jupyter Extensions as Python Packages.ipynb deleted file mode 100644 index 8dc8ca5f32..0000000000 --- a/docs/source/examples/Notebook/Distributing Jupyter Extensions as Python Packages.ipynb +++ /dev/null @@ -1,510 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Distributing Jupyter Extensions as Python Packages" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Overview\n", - "### How can the notebook be extended?\n", - "The Jupyter client and server application are both deeply customizable. Their behavior can be extended by creating, respectively:\n", - "\n", - "- nbextension: a notebook extension\n", - " - a single JS file, or directory of JavaScript, Cascading StyleSheets, etc. that contain at\n", - " minimum a JavaScript module packaged as an\n", - " [AMD modules](https://en.wikipedia.org/wiki/Asynchronous_module_definition)\n", - " that exports a function `load_ipython_extension`\n", - "- server extension: an importable Python module\n", - " - that implements `load_jupyter_server_extension`\n", - "- bundler extension: an importable Python module with generated File -> Download as / Deploy as menu item trigger\n", - " - that implements `bundle`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Why create a Python package for Jupyter extensions?\n", - "Since it is rare to have a server extension that does not have any frontend components (an nbextension), for convenience and consistency, all these client and server extensions with their assets can be packaged and versioned together as a Python package with a few simple commands, or as of Notebook 5.3, handled automatically by your package manager of choice. This makes installing the package of extensions easier and less error-prone for the user." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Installation of Jupyter Extensions\n", - "### Install a Python package containing Jupyter Extensions\n", - "There are several ways that you may get a Python package containing Jupyter Extensions. Commonly, you will use a package manager for your system:\n", - "```shell\n", - "pip install helpful_package\n", - "# or\n", - "conda install helpful_package\n", - "# or\n", - "apt-get install helpful_package\n", - "\n", - "# where 'helpful_package' is a Python package containing one or more Jupyter Extensions\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Automatic installation and Enabling\n", - "> New in Notebook 5.3\n", - "\n", - "The absolute simplest case requires no user interaction at all! Configured correctly, after installing with their package manager of choice, both server and frontend extensions can be enabled by default in the environment where they were installed, i.e. `--sys-prefix`. See the `setup.py` in the example below." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Enable a Server Extension\n", - "\n", - "The simplest case would be to enable a server extension which has no frontend components. \n", - "\n", - "A `pip` user that wants their configuration stored in their home directory would type the following command:\n", - "```shell\n", - "jupyter serverextension enable --py helpful_package\n", - "```\n", - "\n", - "Alternatively, a `virtualenv` or `conda` user can pass `--sys-prefix` which keeps their environment isolated and reproducible. For example:\n", - "```shell\n", - "# Make sure that your virtualenv or conda environment is activated\n", - "[source] activate my-environment\n", - "\n", - "jupyter serverextension enable --py helpful_package --sys-prefix\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Install the nbextension assets" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "If a package also has an nbextension with frontend assets that must be available (but not neccessarily enabled by default), install these assets with the following command:\n", - "```shell\n", - "jupyter nbextension install --py helpful_package # or --sys-prefix if using virtualenv or conda\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Enable nbextension assets\n", - "If a package has assets that should be loaded every time a Jupyter app (e.g. lab, notebook, dashboard, terminal) is loaded in the browser, the following command can be used to enable the nbextension:\n", - "```shell\n", - "jupyter nbextension enable --py helpful_package # or --sys-prefix if using virtualenv or conda\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Did it work? Check by listing Jupyter Extensions.\n", - "After running one or more extension installation steps, you can list what is presently known about nbextensions, server extensions, or bundler extensions. The following commands will list which extensions are available, whether they are enabled, and other extension details:\n", - "\n", - "```shell\n", - "jupyter nbextension list\n", - "jupyter serverextension list\n", - "jupyter bundlerextension list\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Additional resources on creating and distributing packages \n", - "\n", - "> Of course, in addition to the files listed, there are number of other files one needs to build a proper package. Here are some good resources:\n", - "- [The Hitchhiker's Guide to Packaging](https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/quickstart.html)\n", - "- [Repository Structure and Python](https://www.kennethreitz.org/essays/repository-structure-and-python) by Kenneth Reitz\n", - "\n", - "> How you distribute them, too, is important:\n", - "- [Packaging and Distributing Projects](https://python-packaging-user-guide.readthedocs.io/tutorials/distributing-packages/)\n", - "- [conda: Building packages](https://conda.io/docs/building/build.html)\n", - "\n", - "> Here are some tools to get you started:\n", - "- [generator-nbextension](https://github.com/Anaconda-Platform/generator-nbextension)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Example - Server extension" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Creating a Python package with a server extension\n", - "\n", - "Here is an example of a python module which contains a server extension directly on itself. It has this directory structure:\n", - "```\n", - "- setup.py\n", - "- MANIFEST.in\n", - "- my_module/\n", - " - __init__.py\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Defining the server extension\n", - "This example shows that the server extension and its `load_jupyter_server_extension` function are defined in the `__init__.py` file.\n", - "\n", - "#### `my_module/__init__.py`\n", - "\n", - "```python\n", - "def _jupyter_server_extension_paths():\n", - " return [{\n", - " \"module\": \"my_module\"\n", - " }]\n", - "\n", - "\n", - "def load_jupyter_server_extension(nbapp):\n", - " nbapp.log.info(\"my module enabled!\")\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Install and enable the server extension\n", - "Which a user can install with:\n", - "```\n", - "jupyter serverextension enable --py my_module [--sys-prefix]\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Example - Server extension and nbextension" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Creating a Python package with a server extension and nbextension\n", - "Here is another server extension, with a front-end module. It assumes this directory structure:\n", - "\n", - "```\n", - "- setup.py\n", - "- MANIFEST.in\n", - "- my_fancy_module/\n", - " - __init__.py\n", - " - static/\n", - " index.js\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": { - "collapsed": true - }, - "source": [ - "### Defining the server extension and nbextension\n", - "This example again shows that the server extension and its `load_jupyter_server_extension` function are defined in the `__init__.py` file. This time, there is also a function `_jupyter_nbextension_path` for the nbextension.\n", - "\n", - "#### `my_fancy_module/__init__.py`\n", - "\n", - "```python\n", - "def _jupyter_server_extension_paths():\n", - " return [{\n", - " \"module\": \"my_fancy_module\"\n", - " }]\n", - "\n", - "# Jupyter Extension points\n", - "def _jupyter_nbextension_paths():\n", - " return [dict(\n", - " section=\"notebook\",\n", - " # the path is relative to the `my_fancy_module` directory\n", - " src=\"static\",\n", - " # directory in the `nbextension/` namespace\n", - " dest=\"my_fancy_module\",\n", - " # _also_ in the `nbextension/` namespace\n", - " require=\"my_fancy_module/index\")]\n", - "\n", - "def load_jupyter_server_extension(nbapp):\n", - " nbapp.log.info(\"my module enabled!\")\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Install and enable the server extension and nbextension\n", - "\n", - "The user can install and enable the extensions with the following set of commands:\n", - "```\n", - "jupyter nbextension install --py my_fancy_module [--sys-prefix|--user]\n", - "jupyter nbextension enable --py my_fancy_module [--sys-prefix|--system]\n", - "jupyter serverextension enable --py my_fancy_module [--sys-prefix|--system]\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Automatically enabling a server extension and nbextension\n", - "> New in Notebook 5.3\n", - "\n", - "Server extensions and nbextensions can be installed and enabled without any user intervention or post-install scripts beyond ` install `" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "In addition to the `my_fancy_module` file tree, assume:\n", - "- `jupyter-config/`\n", - " - `jupyter_notebook_config.d/`\n", - " - `my_fancy_module.json`\n", - " - `serverconfig/`\n", - " - `notebook.d/`\n", - " - `my_fancy_module.json`" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "#### `jupyter-config/jupyter_notebook_config.d/my_fancy_module.json`\n", - "```json\n", - "{\n", - " \"ServerApp\": {\n", - " \"jpserver_extensions\": {\n", - " \"my_fancy_module\": true\n", - " }\n", - " }\n", - "}\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "#### `jupyter-config/serverconfig/notebook.d/my_fancy_module.json`\n", - "```json\n", - "{\n", - " \"load_extensions\": {\n", - " \"my_fancy_module/index\": true\n", - " }\n", - "}\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Put all of them in place via:\n", - "\n", - "#### `setup.py`\n", - "```python\n", - "import setuptools\n", - "\n", - "setuptools.setup(\n", - " name=\"MyFancyModule\",\n", - " ...\n", - " include_package_data=True,\n", - " data_files=[\n", - " # like `jupyter nbextension install --sys-prefix`\n", - " (\"share/jupyter/nbextensions/my_fancy_module\", [\n", - " \"my_fancy_module/static/index.js\",\n", - " ]),\n", - " # like `jupyter nbextension enable --sys-prefix`\n", - " (\"etc/jupyter/serverconfig/notebook.d\", [\n", - " \"jupyter-config/serverconfig/notebook.d/my_fancy_module.json\"\n", - " ]),\n", - " # like `jupyter serverextension enable --sys-prefix`\n", - " (\"etc/jupyter/jupyter_notebook_config.d\", [\n", - " \"jupyter-config/jupyter_notebook_config.d/my_fancy_module.json\"\n", - " ])\n", - " ],\n", - " ...\n", - " zip_safe=False\n", - ")\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "and last, but not least:\n", - "\n", - "#### `MANIFEST.in`\n", - "```config\n", - "recursive-include jupyter-config *.json\n", - "recursive-include my_fancy_module/static *.js\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "As most package managers will only modify their environment, the eventual configuration will be as if the user had typed:\n", - "```\n", - "jupyter nbextension install --py my_fancy_module --sys-prefix\n", - "jupyter nbextension enable --py my_fancy_module --sys-prefix\n", - "jupyter serverextension enable --py my_fancy_module --sys-prefix\n", - "```\n", - "\n", - "If a user manually `disable`s an extension, that configuration will override the bundled package configuration." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "#### When automagical install fails\n", - "Note this can still fail in certain situations with `pip`, requiring manual use of `install` and `enable` commands.\n", - "\n", - "Non-python-specific package managers (e.g. `conda`, `apt`) may choose not to implement the above behavior at the `setup.py` level, having more ways to put data files in various places at build time." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Example - Bundler extension" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Creating a Python package with a bundlerextension\n", - "\n", - "Here is a bundler extension that adds a *Download as -> Notebook Tarball (tar.gz)* option to the notebook *File* menu. It assumes this directory structure:\n", - "\n", - "```\n", - "- setup.py\n", - "- MANIFEST.in\n", - "- my_tarball_bundler/\n", - " - __init__.py\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Defining the bundler extension\n", - "\n", - "This example shows that the bundler extension and its `bundle` function are defined in the `__init__.py` file.\n", - "\n", - "#### `my_tarball_bundler/__init__.py`\n", - "\n", - "```python\n", - "import tarfile\n", - "import io\n", - "import os\n", - "import nbformat\n", - "\n", - "def _jupyter_bundlerextension_paths():\n", - " \"\"\"Declare bundler extensions provided by this package.\"\"\"\n", - " return [{\n", - " # unique bundler name\n", - " \"name\": \"tarball_bundler\",\n", - " # module containing bundle function\n", - " \"module_name\": \"my_tarball_bundler\",\n", - " # human-redable menu item label\n", - " \"label\" : \"Notebook Tarball (tar.gz)\",\n", - " # group under 'deploy' or 'download' menu\n", - " \"group\" : \"download\",\n", - " }]\n", - "\n", - "\n", - "def bundle(handler, model):\n", - " \"\"\"Create a compressed tarball containing the notebook document.\n", - " \n", - " Parameters\n", - " ----------\n", - " handler : tornado.web.RequestHandler\n", - " Handler that serviced the bundle request\n", - " model : dict\n", - " Notebook model from the configured ContentManager\n", - " \"\"\"\n", - " notebook_filename = model['name']\n", - " notebook_content = nbformat.writes(model['content']).encode('utf-8')\n", - " notebook_name = os.path.splitext(notebook_filename)[0]\n", - " tar_filename = '{}.tar.gz'.format(notebook_name)\n", - " \n", - " info = tarfile.TarInfo(notebook_filename)\n", - " info.size = len(notebook_content)\n", - "\n", - " with io.BytesIO() as tar_buffer:\n", - " with tarfile.open(tar_filename, \"w:gz\", fileobj=tar_buffer) as tar:\n", - " tar.addfile(info, io.BytesIO(notebook_content))\n", - " \n", - " # Set headers to trigger browser download\n", - " handler.set_header('Content-Disposition',\n", - " 'attachment; filename=\"{}\"'.format(tar_filename))\n", - " handler.set_header('Content-Type', 'application/gzip')\n", - " \n", - " # Return the buffer value as the response\n", - " handler.finish(tar_buffer.getvalue())\n", - "```" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "See [Extending the Notebook](../../extending/index.rst) for more documentation about writing nbextensions, server extensions, and bundler extensions." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.6.5" - } - }, - "nbformat": 4, - "nbformat_minor": 1 -} diff --git a/docs/source/examples/Notebook/Importing Notebooks.ipynb b/docs/source/examples/Notebook/Importing Notebooks.ipynb deleted file mode 100644 index c878f0d065..0000000000 --- a/docs/source/examples/Notebook/Importing Notebooks.ipynb +++ /dev/null @@ -1,537 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Importing Jupyter Notebooks as Modules" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "It is a common problem that people want to import code from Jupyter Notebooks.\n", - "This is made difficult by the fact that Notebooks are not plain Python files,\n", - "and thus cannot be imported by the regular Python machinery.\n", - "\n", - "Fortunately, Python provides some fairly sophisticated [hooks](https://www.python.org/dev/peps/pep-0302/) into the import machinery,\n", - "so we can actually make Jupyter notebooks importable without much difficulty,\n", - "and only using public APIs." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import io, os, sys, types" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from IPython import get_ipython\n", - "from nbformat import read\n", - "from IPython.core.interactiveshell import InteractiveShell" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Import hooks typically take the form of two objects:\n", - "\n", - "1. a Module **Loader**, which takes a module name (e.g. `'IPython.display'`), and returns a Module\n", - "2. a Module **Finder**, which figures out whether a module might exist, and tells Python what **Loader** to use" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "def find_notebook(fullname, path=None):\n", - " \"\"\"find a notebook, given its fully qualified name and an optional path\n", - " \n", - " This turns \"foo.bar\" into \"foo/bar.ipynb\"\n", - " and tries turning \"Foo_Bar\" into \"Foo Bar\" if Foo_Bar\n", - " does not exist.\n", - " \"\"\"\n", - " name = fullname.rsplit('.', 1)[-1]\n", - " if not path:\n", - " path = ['']\n", - " for d in path:\n", - " nb_path = os.path.join(d, name + \".ipynb\")\n", - " if os.path.isfile(nb_path):\n", - " return nb_path\n", - " # let import Notebook_Name find \"Notebook Name.ipynb\"\n", - " nb_path = nb_path.replace(\"_\", \" \")\n", - " if os.path.isfile(nb_path):\n", - " return nb_path\n", - " " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Notebook Loader" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Here we have our Notebook Loader.\n", - "It's actually quite simple - once we figure out the filename of the module,\n", - "all it does is:\n", - "\n", - "1. load the notebook document into memory\n", - "2. create an empty Module\n", - "3. execute every cell in the Module namespace\n", - "\n", - "Since IPython cells can have extended syntax,\n", - "the IPython transform is applied to turn each of these cells into their pure-Python counterparts before executing them.\n", - "If all of your notebook cells are pure-Python,\n", - "this step is unnecessary." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "class NotebookLoader(object):\n", - " \"\"\"Module Loader for Jupyter Notebooks\"\"\"\n", - " def __init__(self, path=None):\n", - " self.shell = InteractiveShell.instance()\n", - " self.path = path\n", - " \n", - " def load_module(self, fullname):\n", - " \"\"\"import a notebook as a module\"\"\"\n", - " path = find_notebook(fullname, self.path)\n", - " \n", - " print (\"importing Jupyter notebook from %s\" % path)\n", - " \n", - " # load the notebook object\n", - " with io.open(path, 'r', encoding='utf-8') as f:\n", - " nb = read(f, 4)\n", - " \n", - " \n", - " # create the module and add it to sys.modules\n", - " # if name in sys.modules:\n", - " # return sys.modules[name]\n", - " mod = types.ModuleType(fullname)\n", - " mod.__file__ = path\n", - " mod.__loader__ = self\n", - " mod.__dict__['get_ipython'] = get_ipython\n", - " sys.modules[fullname] = mod\n", - " \n", - " # extra work to ensure that magics that would affect the user_ns\n", - " # actually affect the notebook module's ns\n", - " save_user_ns = self.shell.user_ns\n", - " self.shell.user_ns = mod.__dict__\n", - " \n", - " try:\n", - " for cell in nb.cells:\n", - " if cell.cell_type == 'code':\n", - " # transform the input to executable Python\n", - " code = self.shell.input_transformer_manager.transform_cell(cell.source)\n", - " # run the code in themodule\n", - " exec(code, mod.__dict__)\n", - " finally:\n", - " self.shell.user_ns = save_user_ns\n", - " return mod\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## The Module Finder" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The finder is a simple object that tells you whether a name can be imported,\n", - "and returns the appropriate loader.\n", - "All this one does is check, when you do:\n", - "\n", - "```python\n", - "import mynotebook\n", - "```\n", - "\n", - "it checks whether `mynotebook.ipynb` exists.\n", - "If a notebook is found, then it returns a NotebookLoader.\n", - "\n", - "Any extra logic is just for resolving paths within packages." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "class NotebookFinder(object):\n", - " \"\"\"Module finder that locates Jupyter Notebooks\"\"\"\n", - " def __init__(self):\n", - " self.loaders = {}\n", - " \n", - " def find_module(self, fullname, path=None):\n", - " nb_path = find_notebook(fullname, path)\n", - " if not nb_path:\n", - " return\n", - " \n", - " key = path\n", - " if path:\n", - " # lists aren't hashable\n", - " key = os.path.sep.join(path)\n", - " \n", - " if key not in self.loaders:\n", - " self.loaders[key] = NotebookLoader(path)\n", - " return self.loaders[key]\n" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Register the hook" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Now we register the `NotebookFinder` with `sys.meta_path`" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "sys.meta_path.append(NotebookFinder())" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "After this point, my notebooks should be importable.\n", - "\n", - "Let's look at what we have in the CWD:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "ls nbpackage" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "So I should be able to `import nbpackage.mynotebook`." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import nbpackage.mynotebook" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Aside: displaying notebooks" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Here is some simple code to display the contents of a notebook\n", - "with syntax highlighting, etc." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from pygments import highlight\n", - "from pygments.lexers import PythonLexer\n", - "from pygments.formatters import HtmlFormatter\n", - "\n", - "from IPython.display import display, HTML\n", - "\n", - "formatter = HtmlFormatter()\n", - "lexer = PythonLexer()\n", - "\n", - "# publish the CSS for pygments highlighting\n", - "display(HTML(\"\"\"\n", - "\n", - "\"\"\" % formatter.get_style_defs()\n", - "))" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "def show_notebook(fname):\n", - " \"\"\"display a short summary of the cells of a notebook\"\"\"\n", - " with io.open(fname, 'r', encoding='utf-8') as f:\n", - " nb = read(f, 4)\n", - " html = []\n", - " for cell in nb.cells:\n", - " html.append(\"

%s cell

\" % cell.cell_type)\n", - " if cell.cell_type == 'code':\n", - " html.append(highlight(cell.source, lexer, formatter))\n", - " else:\n", - " html.append(\"
%s
\" % cell.source)\n", - " display(HTML('\\n'.join(html)))\n", - "\n", - "show_notebook(os.path.join(\"nbpackage\", \"mynotebook.ipynb\"))" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "So my notebook has some code cells,\n", - "one of which contains some IPython syntax.\n", - "\n", - "Let's see what happens when we import it" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from nbpackage import mynotebook" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Hooray, it imported! Does it work?" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "mynotebook.foo()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Hooray again!\n", - "\n", - "Even the function that contains IPython syntax works:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "mynotebook.has_ip_syntax()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Notebooks in packages" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We also have a notebook inside the `nb` package,\n", - "so let's make sure that works as well." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "ls nbpackage/nbs" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Note that the `__init__.py` is necessary for `nb` to be considered a package,\n", - "just like usual." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "show_notebook(os.path.join(\"nbpackage\", \"nbs\", \"other.ipynb\"))" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from nbpackage.nbs import other\n", - "other.bar(5)" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "So now we have importable notebooks, from both the local directory and inside packages.\n", - "\n", - "I can even put a notebook inside IPython, to further demonstrate that this is working properly:" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import shutil\n", - "from IPython.paths import get_ipython_package_dir\n", - "\n", - "utils = os.path.join(get_ipython_package_dir(), 'utils')\n", - "shutil.copy(os.path.join(\"nbpackage\", \"mynotebook.ipynb\"),\n", - " os.path.join(utils, \"inside_ipython.ipynb\")\n", - ")" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "and import the notebook from `IPython.utils`" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from IPython.utils import inside_ipython\n", - "inside_ipython.whatsmyname()" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "This approach can even import functions and classes that are defined in a notebook using the `%%cython` magic." - ] - } - ], - "metadata": { - "gist_id": "6011986", - "nbsphinx": { - "execute": "never" - }, - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.5.1+" - } - }, - "nbformat": 4, - "nbformat_minor": 0 -} diff --git a/docs/source/examples/Notebook/JavaScript Notebook Extensions.ipynb b/docs/source/examples/Notebook/JavaScript Notebook Extensions.ipynb deleted file mode 100644 index 8d44100b6b..0000000000 --- a/docs/source/examples/Notebook/JavaScript Notebook Extensions.ipynb +++ /dev/null @@ -1,603 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "# Embracing web standards" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "One of the main reasons why we developed the current notebook web application \n", - "was to embrace the web technology. \n", - "\n", - "By being a pure web application using HTML, JavaScript, and CSS, the Notebook can get \n", - "all the web technology improvement for free. Thus, as browser support for different \n", - "media extend, the notebook web app should be able to be compatible without modification. \n", - "\n", - "This is also true with performance of the User Interface as the speed of JavaScript VM increases. " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The other advantage of using only web technology is that the code of the interface is fully accessible to the end user and is modifiable live.\n", - "Even if this task is not always easy, we strive to keep our code as accessible and reusable as possible.\n", - "This should allow us - with minimum effort - development of small extensions that customize the behavior of the web interface. " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Tampering with the Notebook application" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The first tool that is available to you and that you should be aware of are browser \"developers tool\". The exact naming can change across browser and might require the installation of extensions. But basically they can allow you to inspect/modify the DOM, and interact with the JavaScript code that runs the frontend.\n", - "\n", - " - In Chrome and Safari, Developer tools are in the menu `View > Developer > JavaScript Console` \n", - " - In Firefox you might need to install [Firebug](http://getfirebug.com/)\n", - " \n", - "Those will be your best friends to debug and try different approaches for your extensions." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### Injecting JS" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "#### Using magics" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "The above tools can be tedious for editing edit long JavaScript files. Therefore we provide the `%%javascript` magic. This allows you to quickly inject JavaScript into the notebook. Still the JavaScript injected this way will not survive reloading. Hence, it is a good tool for testing and refining a script.\n", - "\n", - "You might see here and there people modifying css and injecting js into the notebook by reading file(s) and publishing them into the notebook.\n", - "Not only does this often break the flow of the notebook and make the re-execution of the notebook broken, but it also means that you need to execute those cells in the entire notebook every time you need to update the code.\n", - "\n", - "This can still be useful in some cases, like the `%autosave` magic that allows you to control the time between each save. But this can be replaced by a JavaScript dropdown menu to select the save interval." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "## you can inspect the autosave code to see what it does.\n", - "%autosave??" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "#### custom.js" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "To inject JavaScript we provide an entry point: `custom.js` that allows the user to execute and load other resources into the notebook.\n", - "JavaScript code in `custom.js` will be executed when the notebook app starts and can then be used to customize almost anything in the UI and in the behavior of the notebook.\n", - "\n", - "`custom.js` can be found in the `~/.jupyter/custom/custom.js`. You can share your custom.js with others." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "##### Back to theory" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "from jupyter_core.paths import jupyter_config_dir\n", - "jupyter_dir = jupyter_config_dir()\n", - "jupyter_dir" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "and custom js is in " - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "import os.path\n", - "custom_js_path = os.path.join(jupyter_dir, 'custom', 'custom.js')" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": { - "collapsed": false - }, - "outputs": [], - "source": [ - "# my custom js\n", - "if os.path.isfile(custom_js_path):\n", - " with open(custom_js_path) as f:\n", - " print(f.read())\n", - "else:\n", - " print(\"You don't have a custom.js file\") " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Note that `custom.js` is meant to be modified by user. When writing a script, you can define it in a separate file and add a line of configuration into `custom.js` that will fetch and execute the file." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "**Warning** : even if modification of `custom.js` takes effect immediately after browser refresh (except if browser cache is aggressive), *creating* a file in `static/` directory needs a **server restart**." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "## Exercise :" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - " - Create a `custom.js` in the right location with the following content:\n", - "```javascript\n", - "alert(\"hello world from custom.js\")\n", - "```\n", - "\n", - " - Restart your server and open any notebook.\n", - " - Be greeted by custom.js" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "Have a look at [default custom.js](https://github.com/jupyter/notebook/blob/4.0.x/notebook/static/custom/custom.js), to see it's content and for more explanation." - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "### For the quick ones : " - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "We've seen above that you can change the autosave rate by using a magic. This is typically something I don't want to type every time, and that I don't like to embed into my workflow and documents. (readers don't care what my autosave time is). Let's build an extension that allows us to do it. " - ] - }, - { - "cell_type": "markdown", - "metadata": { - "foo": true - }, - "source": [ - "Create a dropdown element in the toolbar (DOM `Jupyter.toolbar.element`), you will need \n", - "\n", - "- `Jupyter.notebook.set_autosave_interval(milliseconds)`\n", - "- know that 1 min = 60 sec, and 1 sec = 1000 ms" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "```javascript\n", - "\n", - "var label = jQuery('