Tools for documentation

Packages

For user documentation, contributor guides, and communications content, we use:

• Sphinx

For developer API documentation (especially for JupyterLab js repos), we use:

• swagger

Source file formats

We use the following input source file formats when developing Sphinx documentation:

• reStructuredText (.rst)

• Markdown (.md)

• Notebook (.ipynb)

A modern code editor should be used. Many are available including Atom, SublimeText, gedit, vim, emacs. Atom is a good choice for new contributors.

Sphinx themes

Our projects use the following themes:

• sphinx_rtd_theme (currently used by Jupyter projects)

• jupyter_sphinx_theme (used by ipywidgets)

Git and Github Resources

If this is your first time working with Github or git, you can leverage the following resources to learn about the tools.

• Try Git

• Github Guides

• Git Real

• Git Documentation

• Git Rebase

Understanding our workflow Setting up a project’s documentation infrastructure