mirror of
https://github.com/jupyter/notebook.git
synced 2025-01-18 11:55:46 +08:00
Merge pull request #1039 from willingc/devinstall
Organize contributor/developer documentation sections
This commit is contained in:
Min RK
commit
a7fc604365
@ -5,4 +5,15 @@ Developer FAQ
|
||||
|
||||
1. How do I install a pre-release version such as a beta or release candidate?
|
||||
|
||||
``python -m pip install notebook --pre --upgrade``
|
||||
.. 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 .
|
||||
|
||||
37
docs/source/development_intro.rst
Normal file
37
docs/source/development_intro.rst
Normal file
@ -0,0 +1,37 @@
|
||||
.. _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,81 +1,52 @@
|
||||
.. _development_js:
|
||||
|
||||
Installing Javascript machinery
|
||||
Installing JavaScript machinery
|
||||
===============================
|
||||
|
||||
Running the Notebook from the source code on GitHub requires some JavaScript
|
||||
tools to build/minify the CSS and JavaScript components. We do these steps when
|
||||
making releases, so there's no need for these tools when installing released
|
||||
versions of the Notebook.
|
||||
.. note::
|
||||
|
||||
First, install `Node.js <https://nodejs.org/>`_. The installers on the
|
||||
Node.js website also include Node's package manager, *npm*. Alternatively,
|
||||
install both of these from your package manager. For example, on Ubuntu or Debian::
|
||||
This section is prepared for contributors to the Notebook source code.
|
||||
Users of the released Notebook do not need to install the JavaScript
|
||||
tools.
|
||||
|
||||
sudo apt-get install nodejs-legacy npm
|
||||
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.
|
||||
|
||||
You can then build the JavaScript and CSS by running::
|
||||
#. Install `Node.js`_ and :program:`npm`.
|
||||
|
||||
python setup.py css js
|
||||
- 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`.
|
||||
|
||||
This will automatically fetch the remaining dependencies (bower, less) and
|
||||
install them in a subdirectory.
|
||||
- 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:
|
||||
|
||||
For quick iteration on the Notebook's JavaScript you can deactivate the use of
|
||||
the bundled and minified JavaScript by using the option
|
||||
``--NotebookApp.ignore_minified_js=True``. This might though highly increase the
|
||||
number of requests that the browser make to the server, but can allow to test
|
||||
JavaScript file modification without going through the compilation step that
|
||||
can take up to 30 sec.
|
||||
.. code:: bash
|
||||
|
||||
sudo apt-get install nodejs-legacy npm
|
||||
|
||||
#. Build the JavaScript and CSS by running:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
python setup.py css js
|
||||
|
||||
This command will automatically fetch the remaining dependencies (bower,
|
||||
less) and install them in a subdirectory.
|
||||
|
||||
Prototyping tip
|
||||
---------------
|
||||
When doing prototyping which needs quick iteration of the Notebook's
|
||||
JavaScript, the bundled and minified JavaScript may be deactivated. To do
|
||||
this, start the Notebook with the option
|
||||
``--NotebookApp.ignore_minified_js=True``. This may highly increase
|
||||
the number of requests that the browser makes to the server; yet, allows
|
||||
testing JavaScript file modification without going through the time consuming
|
||||
compilation step that may take up to 30 seconds.
|
||||
|
||||
|
||||
Making a notebook release
|
||||
-------------------------
|
||||
|
||||
Make sure you have followed the step above and have all the tools to generate
|
||||
the minified JavaScript and CSS files.
|
||||
|
||||
Make sure the repository is clean of any file that could be problematic.
|
||||
You can remove all non-tracked files with:
|
||||
|
||||
.. code::
|
||||
|
||||
$ 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.
|
||||
|
||||
1. Update version number in ``notebook/_version.py``.
|
||||
|
||||
2. Run ``$ python setup.py jsversion``. It will modify (at least)
|
||||
``notebook/static/base/js/namespace.js`` to make the notebook version available
|
||||
from within JavaScript.
|
||||
|
||||
3 . Commit and tag the release with the current version number:
|
||||
|
||||
.. code::
|
||||
|
||||
git commit -am "release $VERSION"
|
||||
git tag $VERSION
|
||||
|
||||
|
||||
4. You are now ready to build the ``sdist`` and ``wheel``:
|
||||
|
||||
.. code::
|
||||
|
||||
$ python setup.py sdist --formats=zip,gztar
|
||||
$ python setup.py bdist_wheel
|
||||
|
||||
|
||||
5. You can now test the ``wheel`` and the ``sdist`` locally before uploading to PyPI.
|
||||
Make sure to use `twine <https://github.com/pypa/twine>`_ to upload the archives over SSL.
|
||||
|
||||
.. code::
|
||||
|
||||
$ twine upload dist/*
|
||||
|
||||
6. If all went well, change the ``notebook/_version.py`` back adding the ``.dev`` suffix.
|
||||
|
||||
7. Push directly on master, not forgetting to push ``--tags``.
|
||||
|
||||
.. _Node.js: https://nodejs.org
|
||||
|
||||
65
docs/source/development_release.rst
Normal file
65
docs/source/development_release.rst
Normal file
@ -0,0 +1,65 @@
|
||||
.. _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
|
||||
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 --formats=zip,gztar
|
||||
python setup.py bdist_wheel
|
||||
|
||||
#. You can now test the ``wheel`` and the ``sdist`` locally before uploading
|
||||
to PyPI. Make sure to use `twine <https://github.com/pypa/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.
|
||||
@ -42,7 +42,9 @@ The Jupyter notebook
|
||||
:maxdepth: 1
|
||||
:caption: Developer Documentation
|
||||
|
||||
development_intro
|
||||
development_js
|
||||
development_release
|
||||
development_faq
|
||||
|
||||
.. toctree::
|
||||
|
||||
Loading…
Reference in New Issue
Block a user