From ac89707eccc830622076558eeb25d05f4f66d08a Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Mon, 14 Mar 2016 20:21:27 +0100 Subject: [PATCH 1/9] DOC: Trying to make a single place for contributor docs See #1193. --- CONTRIBUTING.md | 67 ------------ CONTRIBUTING.rst | 162 ++++++++++++++++++++++++++++ README.md | 56 +--------- docs/source/contributing.rst | 3 + docs/source/development_faq.rst | 19 ---- docs/source/development_intro.rst | 38 ------- docs/source/development_js.rst | 62 ----------- docs/source/development_release.rst | 6 +- docs/source/index.rst | 6 +- setup.py | 9 +- 10 files changed, 182 insertions(+), 246 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst create mode 100644 docs/source/contributing.rst delete mode 100644 docs/source/development_faq.rst delete mode 100644 docs/source/development_intro.rst delete mode 100644 docs/source/development_js.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 20b6caa3e..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -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 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 000000000..d4b0fdd1c --- /dev/null +++ b/CONTRIBUTING.rst @@ -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 diff --git a/README.md b/README.md index 8037fec03..7991ca421 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 000000000..0f53aeaab --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,3 @@ +.. highlight:: sh + +.. include:: ../../CONTRIBUTING.rst diff --git a/docs/source/development_faq.rst b/docs/source/development_faq.rst deleted file mode 100644 index 0ae277e12..000000000 --- a/docs/source/development_faq.rst +++ /dev/null @@ -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 . diff --git a/docs/source/development_intro.rst b/docs/source/development_intro.rst deleted file mode 100644 index 12bd5b533..000000000 --- a/docs/source/development_intro.rst +++ /dev/null @@ -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 `_ -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 \ No newline at end of file diff --git a/docs/source/development_js.rst b/docs/source/development_js.rst deleted file mode 100644 index b199bc02e..000000000 --- a/docs/source/development_js.rst +++ /dev/null @@ -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 diff --git a/docs/source/development_release.rst b/docs/source/development_release.rst index 930cf0bf6..175814159 100644 --- a/docs/source/development_release.rst +++ b/docs/source/development_release.rst @@ -1,6 +1,6 @@ .. _notebook_release: -Making a notebook release +Making a Notebook release ========================= This document guides a contributor through creating a release of the Jupyter @@ -8,11 +8,13 @@ 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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 08c3ac69e..f2e825a59 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 diff --git a/setup.py b/setup.py index ffe7cb3a3..5bf733bec 100755 --- a/setup.py +++ b/setup.py @@ -155,9 +155,14 @@ install_requires = [ ] 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: From 8ae254de85a8a4e35537e58dd67b3ad249ef231d Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Tue, 15 Mar 2016 14:32:49 +0100 Subject: [PATCH 2/9] Some improvements suggested by @willingc See #1208. --- CONTRIBUTING.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index d4b0fdd1c..cce580842 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -23,9 +23,9 @@ steps should get you going:: 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. +If you want the development environment to be available for all users of your +system (assuming you have the necessary rights), just drop the ``--user`` +option. Installing the Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -60,12 +60,14 @@ __ https://nodejs.org Or you can use your system's package manager ... -If you use homebrew on Mac OS X:: +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:: +.. _Homebrew: http://brew.sh/ + +For Debian/Ubuntu systems, you should use the ``nodejs-legacy`` package instead +of the ``node`` package:: sudo apt-get update sudo apt-get install nodejs-legacy npm @@ -75,8 +77,8 @@ 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:: +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:: python setup.py js css From daedb4da79b8efddd737affee73433846e79dcb7 Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Tue, 15 Mar 2016 15:15:33 +0100 Subject: [PATCH 3/9] Add more information about building the docs --- CONTRIBUTING.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index cce580842..746a15de2 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -157,6 +157,13 @@ To build the HTML docs:: cd docs make html +After that, the generated HTML files will be available at +``build/html/index.html``. + +You can automatically check if all hyperlinks are still valid:: + + make linkcheck + Windows users can find ``make.bat`` in the ``docs`` folder. You should also have a look at the `Project Jupyter Documentation Guide`__. From 60f1aa14ea3091034b4ae4d010c7d87417cbd902 Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Tue, 15 Mar 2016 15:28:08 +0100 Subject: [PATCH 4/9] Re-order installation instructions --- CONTRIBUTING.rst | 58 ++++++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 746a15de2..7c4e4a4df 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -15,18 +15,6 @@ __ 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 the development environment to be available for all users of your -system (assuming you have the necessary rights), just drop the ``--user`` -option. - Installing the Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -73,6 +61,22 @@ of the ``node`` package:: sudo apt-get install nodejs-legacy npm +Installing the Jupyter Notebook +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Once you have installed the dependencies mentioned above, use the following +steps:: + + pip install setuptools pip --upgrade --user + git clone https://github.com/jupyter/notebook + cd notebook + pip install -e . --user + +If you want the development environment to be available for all users of your +system (assuming you have the necessary rights), just drop the ``--user`` +option. + + Rebuilding JavaScript and CSS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -108,6 +112,21 @@ See ``git-hooks/README.md`` for more details. Running Tests ------------- +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 + JavaScript Tests ^^^^^^^^^^^^^^^^ @@ -130,21 +149,6 @@ 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 -------------------------- From 13a81daf94073cae83b5b83aa5a4995d7e417cf3 Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Tue, 15 Mar 2016 15:38:31 +0100 Subject: [PATCH 5/9] Remove section about Python Development Libs --- CONTRIBUTING.rst | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7c4e4a4df..892a756f5 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -15,28 +15,12 @@ __ http://jupyter.readthedocs.org/#contributor-documentation Setting Up a Development Environment ------------------------------------ -Installing the Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +For general installation instructions have a look at the `Project Jupyter Installation Guide`__. -Python Development Libraries -"""""""""""""""""""""""""""" +__ https://jupyter.readthedocs.org/en/latest/install.html -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 -""""""""""""""" +Installing Node.js and npm +^^^^^^^^^^^^^^^^^^^^^^^^^^ Building the Notebook from its GitHub source code requires some tools to create and minify JavaScript components and the CSS. From b6a2d81e1e3b78d539a601f633cc34f044403a5d Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Sat, 19 Mar 2016 14:24:08 +0100 Subject: [PATCH 6/9] Add a welcoming sentence suggested by @willingc --- CONTRIBUTING.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 892a756f5..e00e6e2bb 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,7 +1,12 @@ Contributing to the Jupyter Notebook ==================================== -TODO: a welcoming sentence +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 +using the Jupyter Notebook, and introduce yourself on the mailing list and share +what area of the project you are interested in working on. General Guidelines ------------------ From 3c1fcedfaac61693c7ec470b377b04a7caf6c72f Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Sat, 19 Mar 2016 14:37:58 +0100 Subject: [PATCH 7/9] Re-order the node/npm section And add the conda command provided by @damianavila. --- CONTRIBUTING.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index e00e6e2bb..7351d69cb 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -20,7 +20,8 @@ __ http://jupyter.readthedocs.org/#contributor-documentation Setting Up a Development Environment ------------------------------------ -For general installation instructions have a look at the `Project Jupyter Installation Guide`__. +For general installation instructions have a look at the +`Project Jupyter Installation Guide`__. __ https://jupyter.readthedocs.org/en/latest/install.html @@ -29,26 +30,24 @@ Installing Node.js and npm Building the Notebook from its GitHub source code requires some tools to create and minify JavaScript components and the CSS. +Namely, that's Node.js and Node's package manager, ``npm``. -You can use the pre-built installer from the `Node.js website`__. -The installer will include Node.js and Node's package manager, ``npm``. +If you use ``conda``, you can get them with:: -__ https://nodejs.org + conda install -c javascript nodejs -Or you can use your system's package manager ... - -If you use Homebrew_ on Mac OS X:: +If you use `Homebrew `_ on Mac OS X:: brew install node -.. _Homebrew: http://brew.sh/ - For Debian/Ubuntu systems, you should use the ``nodejs-legacy`` package instead of the ``node`` package:: sudo apt-get update sudo apt-get install nodejs-legacy npm +You can also use the installer from the `Node.js website `_. + Installing the Jupyter Notebook ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 6da2ea0cd123f874a359439cc8facb231305fac9 Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Sat, 19 Mar 2016 17:43:40 +0100 Subject: [PATCH 8/9] Restore "development FAQ", but keep only the first item --- docs/source/development_faq.rst | 10 ++++++++++ docs/source/index.rst | 1 + 2 files changed, 11 insertions(+) create mode 100644 docs/source/development_faq.rst diff --git a/docs/source/development_faq.rst b/docs/source/development_faq.rst new file mode 100644 index 000000000..562d7fde8 --- /dev/null +++ b/docs/source/development_faq.rst @@ -0,0 +1,10 @@ +.. _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/index.rst b/docs/source/index.rst index f2e825a59..c1f0c9df4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -44,6 +44,7 @@ The Jupyter notebook contributing development_release + development_faq .. toctree:: :maxdepth: 1 From 69b09b5af0fa3bfd7c92c4715a98be55a3261a7c Mon Sep 17 00:00:00 2001 From: Matthias Geier Date: Thu, 24 Mar 2016 18:48:23 +0100 Subject: [PATCH 9/9] Add instructions for getting the doc-building requirements ... and add docs/requirements.txt --- CONTRIBUTING.rst | 20 +++++++++++++++++--- docs/requirements.txt | 4 ++++ setup.py | 6 ------ 3 files changed, 21 insertions(+), 9 deletions(-) create mode 100644 docs/requirements.txt diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 7351d69cb..88243bd6d 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -137,14 +137,28 @@ or to run just ``notebook/tests/notebook/deletecell.js``:: python -m notebook.jstest notebook/deletecell.js + Building the Documentation -------------------------- -Install dependencies:: +To build the documentation you'll need `Sphinx `_ +and a few other packages. + +To install (and activate) a `conda environment`_ named ``notebook_docs`` +containing all the necessary packages, use:: + + conda env create -f docs/conda_env.yml + source activate notebook_docs # Linux and OS X + activate notebook_docs # Windows + +.. _conda environment: + http://conda.pydata.org/docs/using/envs.html#use-environment-from-file + +If you want to install the necessary packages with ``pip`` instead, use:: - pip install -e .[doc] --user + pip install -r docs/requirements.txt --user -To build the HTML docs:: +Once you have installed the required packages, you can build the docs with:: cd docs make html diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 000000000..fe34f9165 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx>=1.3.6 +sphinx-rtd-theme +sphinxcontrib-spelling +pyenchant diff --git a/setup.py b/setup.py index 5bf733bec..11a2e9644 100755 --- a/setup.py +++ b/setup.py @@ -155,12 +155,6 @@ install_requires = [ ] extras_require = { ':sys_platform != "win32"': ['terminado>=0.3.3'], - 'doc': [ - 'Sphinx>=1.1', - 'sphinx-rtd-theme', - 'sphinxcontrib-spelling', - 'pyenchant', - ], 'test:python_version == "2.7"': ['mock'], 'test': ['nose', 'coverage', 'requests', 'nose_warnings_filters'], }