Preparing for your first contribution
Developing your contribution
Clone the repository
Edit the documentation source file
Creating a pull request
Our documentation uses reStructured Text, Markdown, and Jupyter notebooks.
We use Sphinx extensively to build documentation.
We use Transifex to help translate documentation to multiple languages.
We host our documentation on Read the Docs.
Jupyter’s documentation is split across several projects, listed on the Jupyter documentation home page. These instructions apply to all Jupyter projects, though some projects have further contribution guidelines.
Fork the appropriate project repository on GitHub, depending on which project’s documentation you want to contribute to.
Clone the repository to your system.
Source files for projects are typically found in the project’s docs/source
directory. The reStructured text filenames end with .rst, and Jupyter
notebook files end with .ipynb.
In your favorite text editor, make desired changes to the .rst file when
working with a reStructured text source file.
If a notebook file requires editing, you will need to install Jupyter
notebook according to the Installation document. Then,
run the Jupyter notebook and edit the desired file. Before saving the
Jupyter .ipynb file, please clear the output cells. Save the file and
test your change.
Sphinx should be installed to test your documentation changes. For best results,
we recommend that you install the stable development version Sphinx
(pip install git+https://github.com/sphinx-doc/sphinx@stable) or the
current released version of Sphinx (pip install sphinx).
pip install git+https://github.com/sphinx-doc/sphinx@stable
pip install sphinx
In addition, you may need the following packages: sphinxcontrib-spelling, sphinx_rtd_theme, nbsphinx, pyenchant, recommonmark 0.4.0 and jupyter_sphinx_theme, which can be installed via pip install sphinxcontrib-spelling sphinx_rtd_theme nbsphinx pyenchant recommonmark==0.4.0 jupyter_sphinx_theme.
pip install sphinxcontrib-spelling sphinx_rtd_theme nbsphinx pyenchant recommonmark==0.4.0 jupyter_sphinx_theme
If you are on Linux, you may also need to install the Enchant C library by running sudo apt-get install enchant.
sudo apt-get install enchant
Once everything is installed, the following commands should be executed using the Terminal/command line from
the docs directory:
make html builds a local html version of the documentation. The output
message will either display errors or provide the location of the html documents.
For example, the location provided may be build/html and to view these
documents in your browser enter open build/html/index.html.
make linkcheck will check whether the external links in the
documentation are valid or if they are not longer current (i.e. cause a 500
not found error).
Note: We recommend using Python 3.4+ for building the documentation. If you are editing the documentation, you can use Python 2.7.9+ or the Github editor.
Once you are satisfied with your changes, submit a GitHub pull request, per
the instructions above. If the documentation change is related to an open
GitHub issue, please mention the issue number in the pull request message.
A project reviewer will look over your changes and provide feedback or merge
your changes into the documentation.
Feel free to ask questions in the Google Group for Jupyter or on an open issue