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

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

    - [Sphinx](http://www.sphinx-doc.org/en/stable/)

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>`_
Tools for documentation
=======================

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

    - `Sphinx <http://www.sphinx-doc.org/en/stable>`_

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>`_
Use rst links in rst doc
Use rst links in rst doc
