adding documentation

.gitignore

@@ -13,3 +13,4 @@ future
 *.pyc
 gits*
 .ipynb_checkpoints
+docs/_build

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/advanced.md

@@ -0,0 +1,20 @@
+# Advanced functionality
+
+Below are some advanced functionality and tips.
+
+## Fine tuning
+
+Jupyter magic commands are commented when exporting the notebook to text, except for the `markdown` and the `hydrogen` format. If you want to change this for a single line, add a `#escape` or `#noescape` flag on the same line as the magic, or a `"comment_magics": true` or `false` entry in the notebook metadata, in the `"jupytext"` section. Or set your preference globally on the contents manager by adding this line to `.jupyter/jupyter_notebook_config.py`:
+```python
+c.ContentsManager.comment_magics = True # or False
+```
+
+Also, you may want some cells to be active only in the Python, or R Markdown representation. For this, use the `active` cell metadata. Set `"active": "ipynb"` if you want that cell to be active only in the Jupyter notebook. And `"active": "py"` if you want it to be active only in the Python script. And `"active": "ipynb,py"` if you want it to be active in both, but not in the R Markdown representation...
+
+## Extending the `light` and `percent` formats to more languages
+
+You want to extend the `light` and `percent` format to another language? In principle that is easy, and you will only have to:
+- document the language extension and comment by adding one line to `_SCRIPT_EXTENSIONS` in `languages.py`.
+- contribute a sample notebook in `tests\notebooks\ipynb_[language]`.
+- add two tests in `test_mirror.py`: one for the `light` format, and another one for the `percent` format.
+- Make sure that the tests pass, and that the text representations of your notebook, found in  `tests\notebooks\mirror\ipynb_to_script` and `tests\notebooks\mirror\ipynb_to_percent`, are valid scripts.

docs/conf.py

@@ -0,0 +1,70 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = "Jupytext"
+copyright = "2018-2019, The Jupytext Team"
+author = "The Jupytext Team"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx_copybutton", "recommonmark"]
+
+html_context = {
+    "display_github": True,  # Integrate GitHub
+    "github_user": "mwouts",  # Username
+    "github_repo": "jupytext",  # Repo name
+    "github_version": "master",  # Version
+    "conf_py_path": "/docs/",  # Path in the checkout to the docs root
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+pygments_style = "sphinx"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "jupytext"
+
+from recommonmark.transform import AutoStructify
+
+
+def setup(app):
+    app.add_config_value(
+        "recommonmark_config", {"auto_toc_tree_section": "Contents"}, True
+    )
+    app.add_transform(AutoStructify)

docs/doc-requirements.txt

@@ -0,0 +1,5 @@
+sphinx
+sphinx_rtd_theme
+sphinx_copybutton
+jupytext
+recommonmark

docs/examples.md

@@ -0,0 +1,47 @@
+# Usecases for Jupytext
+
+## Writing notebooks as plain text
+
+You like to work with scripts? The good news is that plain scripts, which you can draft and test in your favorite IDE, open transparently as notebooks in Jupyter when using Jupytext. Run the notebook in Jupyter to generate the outputs, [associate](using-server.html#paired-notebooks) an `.ipynb` representation, save and share your research as either a plain script or as a traditional Jupyter notebook with outputs.
+
+## Collaborating on Jupyter Notebooks
+
+With Jupytext, collaborating on Jupyter notebooks with Git becomes as easy as collaborating on text files.
+
+The setup is straightforward:
+- Open your favorite notebook in Jupyter notebook
+- [Associate](using-server.html#paired-notebooks) a `.py` representation (for instance) to that notebook
+- Save the notebook, and put the Python script under Git control. Sharing the `.ipynb` file is possible, but not required.
+
+Collaborating then works as follows:
+- Your collaborator pulls your script.
+- The script opens as a notebook in Jupyter, with no outputs (in JupyterLab right-click the script and use the open-with context menu).
+- They run the notebook and save it. Outputs are regenerated, and a local `.ipynb` file is created.
+- Note that, alternatively, the `.ipynb` file could have been regenerated with `jupytext --sync notebook.py`.
+- They change the notebook, and push their updated script. The diff is nothing else than a standard diff on a Python script.
+- You pull the changed script, and refresh your browser. Input cells are updated. The outputs from cells that were changed are removed. Your variables are untouched, so you have the option to run only the modified cells to get the new outputs.
+
+## Code refactoring
+
+In the animation below we propose a quick demo of Jupytext. While the example remains simple, it shows how your favorite text editor or IDE can be used to edit your Jupyter notebooks. IDEs are more convenient than Jupyter for navigating through code, editing and executing cells or fractions of cells, and debugging.
+
+- We start with a Jupyter notebook.
+- The notebook includes a plot of the world population. The plot legend is not in order of decreasing population, we'll fix this.
+- We want the notebook to be saved as both a `.ipynb` and a `.py` file: we select _Pair Notebook with a light Script_ in either the [Jupytext menu](install.html#jupytext-menu-in-jupyter-notebook) in Jupyter Notebook, or in the [Jupytext commands](install.html#jupytext-commands-in-jupyterlab) in JupyterLab. This has the effect of adding a `"jupytext": {"formats": "ipynb,py:light"},` entry to the notebook metadata.
+- The Python script can be opened with PyCharm:
+  - Navigating in the code and documentation is easier than in Jupyter.
+  - The console is convenient for quick tests. We don't need to create cells for this.
+  - We find out that the columns of the data frame were not in the correct order. We update the corresponding cell, and get the correct plot.
+- The Jupyter notebook is refreshed in the browser. Modified inputs are loaded from the Python script. Outputs and variables are preserved. We finally rerun the code and get the correct plot.
+
+![](https://gist.githubusercontent.com/mwouts/13de42d8bb514e4acf6481c580feffd0/raw/b8dd28f44678f8c91f262da2381276fc4d03b00a/JupyterPyCharm.gif)
+
+## Importing Jupyter Notebooks as modules
+
+Jupytext allows to import code from other Jupyter notebooks in a very simple manner. Indeed, all you need to do is to pair the notebook that you wish to import with a script, and import the resulting script.
+
+If the notebook contains demos and plots that you don't want to import, mark those cells as either
+- _active_ only in the `ipynb` format, with the `{"active": "ipynb"}` cell metadata, or with an `active-ipynb` tag (you may use the [jupyterlab-celltags](https://github.com/jupyterlab/jupyterlab-celltags) extension for this).
+- _frozen_, using the [freeze extension](https://jupyter-contrib-nbextensions.readthedocs.io/en/latest/nbextensions/freeze/readme.html) for Jupyter notebook.
+
+Inactive cells will be commented in the paired script, and consequently will not be executed when the script is imported.