Skip to content
This repository has been archived by the owner on Feb 10, 2019. It is now read-only.

Commit

Permalink
DOC: Trying to make a single place for contributor docs
Browse files Browse the repository at this point in the history
mgeier committed Mar 14, 2016
1 parent 6cb736a commit ac89707
Showing 10 changed files with 182 additions and 246 deletions.
67 changes: 0 additions & 67 deletions CONTRIBUTING.md

This file was deleted.

162 changes: 162 additions & 0 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
@@ -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
56 changes: 4 additions & 52 deletions README.md
Original file line number Diff line number Diff line change
@@ -69,61 +69,13 @@ In browser, open `http://192.168.99.104:8888`.
NOTE: With the deprecated `boot2docker`, use the command `boot2docker ip` to
determine the URL.

## Development Installation Quickstart
Detailed [Developer Documentation](http://jupyter-notebook.readthedocs.org/en/latest)
is available on ReadTheDocs.

* Ensure that you have node/npm installed (e.g. `brew install node` on OS X)
* Clone this repo and `cd` into it
* `pip install --pre -e .`

NOTE: For **Debian/Ubuntu** systems, if you're installing the system node you
need to use the 'nodejs-legacy' package and not the 'node' package.

For more detailed development install instructions (e.g. recompiling javascript
and css, running tests), see the
[Developer Documentation](https://jupyter-notebook.readthedocs.org/en/latest/development_js.html)
on ReadTheDocs and the [contributing guide](CONTRIBUTING.md).

### Ubuntu Trusty

```
sudo apt-get install nodejs-legacy npm python-virtualenv python-dev
# ensure setuptools/pip are up-to-date
pip install --upgrade setuptools pip
git clone https://github.com/jupyter/notebook.git
cd notebook
pip install --pre -e .
jupyter notebook
```

### FreeBSD

```
cd /usr/ports/www/npm
sudo make install # (Be sure to select the "NODE" option)
cd /usr/ports/devel/py-pip
sudo make install
cd /usr/ports/devel/py-virtualenv
sudo make install
cd /usr/ports/shells/bash
sudo make install
mkdir -p ~/.virtualenvs
python2.7 -m virtualenv ~/.virtualenvs/notebook
bash
source ~/.virtualenvs/notebook/bin/activate
pip install --upgrade setuptools pip pycurl
git clone https://github.com/jupyter/notebook.git
cd notebook
pip install -r requirements.txt -e .
jupyter notebook
```
## Development Installation

See `CONTRIBUTING.rst` for how to set up a local development installation.

## Contributing

If you are interested in contributing to the project, you can find information about the
contribution process in the [Jupyter Contribution Guidelines]
(http://jupyter.readthedocs.org/en/latest/contrib_guide_code.html).
If you are interested in contributing to the project, see `CONTRIBUTING.rst`.

## Resources
- [Project Jupyter website](https://jupyter.org)
3 changes: 3 additions & 0 deletions docs/source/contributing.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.. highlight:: sh

.. include:: ../../CONTRIBUTING.rst
19 changes: 0 additions & 19 deletions docs/source/development_faq.rst

This file was deleted.

38 changes: 0 additions & 38 deletions docs/source/development_intro.rst

This file was deleted.

62 changes: 0 additions & 62 deletions docs/source/development_js.rst

This file was deleted.

6 changes: 4 additions & 2 deletions docs/source/development_release.rst
Original file line number Diff line number Diff line change
@@ -1,18 +1,20 @@
.. _notebook_release:

Making a notebook release
Making a Notebook release
=========================

This document guides a contributor through creating a release of the Jupyter
notebook.

Check installed tools
---------------------
Review :ref:`development_js`. Make sure all the tools needed to generate the

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
6 changes: 2 additions & 4 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -40,12 +40,10 @@ The Jupyter notebook

.. toctree::
:maxdepth: 1
:caption: Developer Documentation
:caption: Contributor Documentation

development_intro
development_js
contributing
development_release
development_faq

.. toctree::
:maxdepth: 1
9 changes: 7 additions & 2 deletions setup.py
Original file line number Diff line number Diff line change
@@ -155,9 +155,14 @@
]
extras_require = {
':sys_platform != "win32"': ['terminado>=0.3.3'],
'doc': ['Sphinx>=1.1'],
'doc': [
'Sphinx>=1.1',
'sphinx-rtd-theme',
'sphinxcontrib-spelling',
'pyenchant',
],
'test:python_version == "2.7"': ['mock'],
'test': ['nose', 'requests', 'nose_warnings_filters'],
'test': ['nose', 'coverage', 'requests', 'nose_warnings_filters'],
}

if 'setuptools' in sys.modules:

0 comments on commit ac89707

Please sign in to comment.