Tools for documentation
=======================

.. contents:: Contents
   :local:

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

- `Sphinx <https://www.sphinx-doc.org/en/master/contents.html>`_

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

- `swagger <http://swagger.io/>`_

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 <https://atom.io/>`_ 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  <https://try.github.io/levels/1/challenges/1>`_
* `Github Guides  <https://guides.github.com>`_
* `Git Real  <https://www.codeschool.com/courses/git-real>`_
* `Git Documentation <https://git-scm.com/documentation>`_
* `Git Rebase <https://github.com/pydata/pandas/wiki/Git-Workflows#user-content-git-rebase>`_