CONTRIBUTING.rst 6.72 KB
Newer Older
1
2
3
Contributing to the Jupyter Notebook
====================================

4
5
6
7
If you're reading this section, you're probably interested in contributing to
Jupyter.  Welcome and thanks for your interest in contributing!

Please take a look at the Contributor documentation, familiarize yourself with
8
9
using the Jupyter Notebook, and introduce yourself on the mailing list and
share what area of the project you are interested in working on.
10
11
12
13
14
15
16

General Guidelines
------------------

For general documentation about contributing to Jupyter projects, see the
`Project Jupyter Contributor Documentation`__.

17
__ https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html
18
19
20
21
22


Setting Up a Development Environment
------------------------------------

23
24
Installing Node.js and npm
^^^^^^^^^^^^^^^^^^^^^^^^^^
25
26

Building the Notebook from its GitHub source code requires some tools to
27
28
29
create and minify JavaScript components and the CSS,
specifically Node.js and Node's package manager, ``npm``.
It should be node version ≥ 6.0.
30

Matthias Geier's avatar
Matthias Geier committed
31
If you use ``conda``, you can get them with::
32

33
    conda install -c conda-forge nodejs
34

35
If you use `Homebrew <https://brew.sh/>`_ on Mac OS X::
36
37
38

    brew install node

39
40
Installation on Linux may vary, but be aware that the `nodejs` or `npm` packages
included in the system package repository may be too old to work properly.
41

Matthias Geier's avatar
Matthias Geier committed
42
43
You can also use the installer from the `Node.js website <https://nodejs.org>`_.

44

45
46
47
48
49
50
Installing the Jupyter Notebook
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once you have installed the dependencies mentioned above, use the following
steps::

51
    pip install --upgrade setuptools pip
52
53
    git clone https://github.com/jupyter/notebook
    cd notebook
54
    pip install -e .
55

56
57
If you are using a system-wide Python installation and you only want to install the notebook for you,
you can add ``--user`` to the install commands.
58

59
60
61
62
Once you have done this, you can launch the master branch of Jupyter notebook
from any directory in your system with::

    jupyter notebook
danagilliann's avatar
danagilliann committed
63
64
65
66
67
68
69

Verification
^^^^^^^^^^^^

While running the notebook, select one of your notebook files (the file will have the extension ``.ipynb``).
In the top tab you will click on "Help" and then click on "About". In the pop window you will see information about the version of Jupyter that you are running. You will see "The version of the notebook server is:".
If you are working in development mode, you will see that your version of Jupyter notebook will include the word "dev".
70

danagilliann's avatar
danagilliann committed
71
.. image:: ./docs/source/_static/images/jupyter-verification.png
Rosa Swaby's avatar
Rosa Swaby committed
72
   :width: 40pt
73

danagilliann's avatar
danagilliann committed
74
If it does not include the word "dev", you are currently not working in development mode and should follow the steps below to uninstall and reinstall Jupyter.
75

danagilliann's avatar
danagilliann committed
76
77
78
79
80
81
82
Troubleshooting the Installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you do not see that your Jupyter Notebook is not running on dev mode, it's possible that you are
running other instances of Jupyter Notebook. You can try the following steps:

1. Uninstall all instances of the notebook package. These include any installations you made using
83
84
85
   pip or conda.
2. Run ``python3 -m pip install -e .`` in the notebook repository to install the notebook from there.
3. Run ``npm run build`` to make sure the Javascript and CSS are updated and compiled.
danagilliann's avatar
danagilliann committed
86
4. Launch with ``python3 -m notebook --port 8989``, and check that the browser is pointing to ``localhost:8989``
danagilliann's avatar
danagilliann committed
87
88
89
90
91
   (rather than the default 8888). You don't necessarily have to launch with port 8989, as long as you use
   a port that is neither the default nor in use, then it should be fine.
5. Verify the installation with the steps in the previous section.


92
93
94
95
Rebuilding JavaScript and CSS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There is a build step for the JavaScript and CSS in the notebook.
96
97
To make sure that you are working with up-to-date code, you will need to run
this command whenever there are changes to JavaScript or LESS sources::
98

Grant Nestor's avatar
Grant Nestor committed
99
    npm run build
100

101
102
103
**IMPORTANT:** Don't forget to run ``npm run build`` after switching branches.
When switching between branches of different versions (e.g. ``4.x`` and
``master``), run ``pip install -e .``. If you have tried the above and still
Grant Nestor's avatar
Grant Nestor committed
104
105
106
107
find that the notebook is not reflecting the current source code, try cleaning
the repo with ``git clean -xfd`` and reinstalling with ``pip install -e .``.

Development Tip
108
109
"""""""""""""""

110
When doing development, you can use this command to automatically rebuild
Grant Nestor's avatar
Grant Nestor committed
111
JavaScript and LESS sources as they are modified::
112
113
114
115
116
117

    npm run build:watch

Git Hooks
"""""""""

Grant Nestor's avatar
Grant Nestor committed
118
If you want to automatically update dependencies and recompile JavaScript and
119
CSS after checking out a new commit, you can install post-checkout and
Grant Nestor's avatar
Grant Nestor committed
120
post-merge hooks which will do it for you::
121
122
123
124
125
126
127
128
129

    git-hooks/install-hooks.sh

See ``git-hooks/README.md`` for more details.


Running Tests
-------------

130
131
132
133
134
Python Tests
^^^^^^^^^^^^

Install dependencies::

135
    pip install -e '.[test]'
136
137
138

To run the Python tests, use::

139
    pytest
140
141
142

If you want coverage statistics as well, you can run::

143
    py.test --cov notebook -v --pyargs notebook
144

145
146
147
148
149
150
JavaScript Tests
^^^^^^^^^^^^^^^^

To run the JavaScript tests, you will need to have PhantomJS and CasperJS
installed::

151
    npm install -g casperjs phantomjs-prebuilt
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166

Then, to run the JavaScript tests::

    python -m notebook.jstest [group]

where ``[group]`` is an optional argument that is a path relative to
``notebook/tests/``.
For example, to run all tests in ``notebook/tests/notebook``::

    python -m notebook.jstest notebook

or to run just ``notebook/tests/notebook/deletecell.js``::

    python -m notebook.jstest notebook/deletecell.js

167

168
169
170
Building the Documentation
--------------------------

171
172
To build the documentation you'll need `Sphinx <http://www.sphinx-doc.org/>`_,
`pandoc <http://pandoc.org/>`_ and a few other packages.
173
174

To install (and activate) a `conda environment`_ named ``notebook_docs``
175
containing all the necessary packages (except pandoc), use::
176

Carol Willing's avatar
Carol Willing committed
177
    conda env create -f docs/environment.yml
hdtee1's avatar
hdtee1 committed
178
    conda activate notebook_docs  # Linux and OS X
179
180
181
    activate notebook_docs         # Windows

.. _conda environment:
182
    https://conda.io/docs/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file
183

hdtee1's avatar
hdtee1 committed
184
If you want to install the necessary packages with ``pip``, use the following instead::
185

186
    pip install -r docs/doc-requirements.txt
187

188
Once you have installed the required packages, you can build the docs with::
189
190
191
192

    cd docs
    make html

193
After that, the generated HTML files will be available at
Carol Willing's avatar
Carol Willing committed
194
``build/html/index.html``. You may view the docs in your browser.
195
196
197
198
199

You can automatically check if all hyperlinks are still valid::

    make linkcheck

200
201
202
203
Windows users can find ``make.bat`` in the ``docs`` folder.

You should also have a look at the `Project Jupyter Documentation Guide`__.

204
__ https://jupyter.readthedocs.io/en/latest/contrib_docs/index.html