See #1193.
Matthias Geier
10 years ago
parent
6cb736afd7
commit
ac89707ecc
@ -1,67 +0,0 @@
|
||||
# Contributing
|
||||
|
||||
We follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
|
||||
|
||||
For development installation instructions, see the [README](README.md#dev-quickstart).
|
||||
|
||||
## Managing static files
|
||||
|
||||
The notebook relies on static dependencies (which are installed with Bower), its own minified JavaScript, and CSS compiled from LESS.
|
||||
|
||||
### Static dependencies
|
||||
|
||||
To install the static dependencies, run:
|
||||
|
||||
python setup.py jsdeps
|
||||
|
||||
You can also pass a `-f` flag to this command to force Bower to run, if necessary.
|
||||
|
||||
### JavaScript
|
||||
|
||||
To compile the JavaScript, run:
|
||||
|
||||
npm run build:js
|
||||
|
||||
### Compiling CSS
|
||||
|
||||
To compile the CSS from LESS, run:
|
||||
|
||||
python setup.py css
|
||||
|
||||
### Git hooks
|
||||
|
||||
If you want to automatically update dependencies, recompile the JavaScript, and recompile the CSS after checking out a new commit, you can install post-checkout and post-merge hooks which will do it for you:
|
||||
|
||||
./git-hooks/install-hooks.sh
|
||||
|
||||
See the [git-hooks readme](git-hooks/README.md) for more details.
|
||||
|
||||
## Running tests
|
||||
|
||||
### JavaScript tests
|
||||
|
||||
To run the JavaScript tests, you will need to have PhantomJS and CasperJS installed:
|
||||
|
||||
npm install -g casperjs phantomjs@1.9.18
|
||||
|
||||
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
|
||||
|
||||
### Python tests
|
||||
|
||||
To run Python tests, run:
|
||||
|
||||
nosetests notebook
|
||||
|
||||
If you want coverage statistics as well, you can run:
|
||||
|
||||
nosetests --with-coverage --cover-package=notebook notebook
|
||||
@ -0,0 +1,162 @@
|
||||
Contributing to the Jupyter Notebook
|
||||
====================================
|
||||
|
||||
TODO: a welcoming sentence
|
||||
|
||||
General Guidelines
|
||||
------------------
|
||||
|
||||
For general documentation about contributing to Jupyter projects, see the
|
||||
`Project Jupyter Contributor Documentation`__.
|
||||
|
||||
__ http://jupyter.readthedocs.org/#contributor-documentation
|
||||
|
||||
|
||||
Setting Up a Development Environment
|
||||
------------------------------------
|
||||
|
||||
If you have already installed the dependencies mentioned below, the following
|
||||
steps should get you going::
|
||||
|
||||
pip install setuptools pip --upgrade --user
|
||||
git clone https://github.com/jupyter/notebook
|
||||
cd notebook
|
||||
pip install -e . --user
|
||||
|
||||
If you want this to be available for all users of your system (assuming you
|
||||
have the necessary rights) or if you are running the commands in a virtualenv,
|
||||
just drop the ``--user`` option.
|
||||
|
||||
Installing the Dependencies
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Python Development Libraries
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
On Debian/Ubuntu systems, you can get them with::
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install python3-dev
|
||||
|
||||
The development libraries might be needed for the installation of *PyZMQ*,
|
||||
*Tornado* and *Jinja2*.
|
||||
|
||||
Alternatively -- if you prefer -- you can also install those packages directly
|
||||
with your package manager::
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install python3-zmq python3-tornado python3-jinja2
|
||||
|
||||
Node.js and npm
|
||||
"""""""""""""""
|
||||
|
||||
Building the Notebook from its GitHub source code requires some tools to
|
||||
create and minify JavaScript components and the CSS.
|
||||
|
||||
You can use the pre-built installer from the `Node.js website`__.
|
||||
The installer will include Node.js and Node's package manager, ``npm``.
|
||||
|
||||
__ https://nodejs.org
|
||||
|
||||
Or you can use your system's package manager ...
|
||||
|
||||
If you use homebrew on Mac OS X::
|
||||
|
||||
brew install node
|
||||
|
||||
For Debian/Ubuntu systems, you need to use the ``nodejs-legacy`` package and
|
||||
not the ``node`` package::
|
||||
|
||||
sudo apt-get update
|
||||
sudo apt-get install nodejs-legacy npm
|
||||
|
||||
|
||||
Rebuilding JavaScript and CSS
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
There is a build step for the JavaScript and CSS in the notebook.
|
||||
You will need to run this command whenever there are changes to JavaScript or
|
||||
LESS sources::
|
||||
|
||||
python setup.py js css
|
||||
|
||||
Prototyping Tip
|
||||
"""""""""""""""
|
||||
|
||||
When doing prototyping which needs quick iteration of the Notebook's
|
||||
JavaScript, run this in the root of the repository::
|
||||
|
||||
npm run build:watch
|
||||
|
||||
This will cause WebPack to monitor the files you edit and recompile them on the
|
||||
fly.
|
||||
|
||||
Git Hooks
|
||||
"""""""""
|
||||
|
||||
If you want to automatically update dependencies, recompile the JavaScript, and
|
||||
recompile the CSS after checking out a new commit, you can install
|
||||
post-checkout and post-merge hooks which will do it for you::
|
||||
|
||||
git-hooks/install-hooks.sh
|
||||
|
||||
See ``git-hooks/README.md`` for more details.
|
||||
|
||||
|
||||
Running Tests
|
||||
-------------
|
||||
|
||||
JavaScript Tests
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
To run the JavaScript tests, you will need to have PhantomJS and CasperJS
|
||||
installed::
|
||||
|
||||
npm install -g casperjs phantomjs@1.9.18
|
||||
|
||||
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
|
||||
|
||||
Python Tests
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Install dependencies::
|
||||
|
||||
pip install -e .[test] --user
|
||||
|
||||
To run the Python tests, use::
|
||||
|
||||
nosetests
|
||||
|
||||
If you want coverage statistics as well, you can run::
|
||||
|
||||
nosetests --with-coverage --cover-package=notebook notebook
|
||||
|
||||
Building the Documentation
|
||||
--------------------------
|
||||
|
||||
Install dependencies::
|
||||
|
||||
pip install -e .[doc] --user
|
||||
|
||||
To build the HTML docs::
|
||||
|
||||
cd docs
|
||||
make html
|
||||
|
||||
Windows users can find ``make.bat`` in the ``docs`` folder.
|
||||
|
||||
You should also have a look at the `Project Jupyter Documentation Guide`__.
|
||||
|
||||
__ https://jupyter.readthedocs.org/en/latest/contrib_guide_docs.html
|
||||
@ -0,0 +1,3 @@
|
||||
.. highlight:: sh
|
||||
|
||||
.. include:: ../../CONTRIBUTING.rst
|
||||
@ -1,19 +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
|
||||
|
||||
2. What are the basic steps for a development install?
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/jupyter/notebook
|
||||
cd notebook
|
||||
python setup.py js css
|
||||
pip install -e .
|
||||
@ -1,38 +0,0 @@
|
||||
.. _development_intro:
|
||||
|
||||
Want to contribute?
|
||||
===================
|
||||
|
||||
Here are some resources to help you get started with setting up a
|
||||
development environment, how to contribute, and technical aspects of
|
||||
contributing.
|
||||
|
||||
|
||||
Notebook project developer guides
|
||||
---------------------------------
|
||||
These guides provide information about specific topics related to developing
|
||||
the Notebook.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
development_js
|
||||
development_release
|
||||
development_faq
|
||||
|
||||
|
||||
Jupyter developer guides
|
||||
------------------------
|
||||
The Project Jupyter organization has more general documentation about
|
||||
contributing to Jupyter projects. Currently, this is available in the Jupyter
|
||||
documentation in the
|
||||
`Developer Documentation <https://jupyter.readthedocs.org/en/latest/#dev-docs>`_
|
||||
section.
|
||||
|
||||
Some of the topics include:
|
||||
|
||||
- Submitting a Bug
|
||||
- Submitting an Enhancement Proposal
|
||||
- Contributing to the Documentation
|
||||
- Git and Github Resources
|
||||
- Contributing to the Code
|
||||
@ -1,62 +0,0 @@
|
||||
.. _development_js:
|
||||
|
||||
Installing JavaScript machinery
|
||||
===============================
|
||||
|
||||
.. note::
|
||||
|
||||
This section is prepared for contributors to the Notebook source code.
|
||||
Users of the released Notebook do not need to install the JavaScript
|
||||
tools.
|
||||
|
||||
Building the Notebook from its GitHub source code requires some tools to
|
||||
create and minify JavaScript components and the CSS. These tools and the
|
||||
following steps are used when making a Notebook release.
|
||||
|
||||
#. Install `Node.js`_ and :program:`npm`.
|
||||
|
||||
- Using the installers on `Node.js`_ website:
|
||||
Select a pre-built installer
|
||||
on the `Node.js`_ website. The installer will include Node.js and
|
||||
Node's package manager, :program:`npm`.
|
||||
|
||||
- Using system's package manager:
|
||||
Install Node.js and :program:`npm` using the
|
||||
system's package manager. For example, the command for Ubuntu or Debian
|
||||
is:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo apt-get install nodejs-legacy npm
|
||||
|
||||
#. Install the notebook:
|
||||
|
||||
In the notebook repo, do a development install:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
pip install -e .
|
||||
|
||||
#. Rebuild JavaScript and CSS
|
||||
|
||||
There is a build step for the JavaScript and CSS in the notebook.
|
||||
You will need to run this command whenever there are changes to JavaScript or LESS sources:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
python setup.py js css
|
||||
|
||||
This command will automatically fetch any missing dependencies (bower,
|
||||
less) and install them in a subdirectory.
|
||||
|
||||
|
||||
Prototyping tip
|
||||
---------------
|
||||
|
||||
When doing prototyping which needs quick iteration of the Notebook's
|
||||
JavaScript, run `npm run build:watch` in the root of the repository.
|
||||
This will cause WebPack to monitor the files you edit and recompile
|
||||
them on the fly.
|
||||
|
||||
|
||||
.. _Node.js: https://nodejs.org
|
||||
Loading…
Reference in new issue