python library docs

docs/index.md

@@ -7,5 +7,6 @@
 * [Installation](install)
 * [Using Jupytext in Jupyter](using-server)
 * [Using at the command line](using-cli)
+* [Using as a Python libary](using-library)
 * [Supported document formats](formats)
 * [Frequently Asked Questions](faq)

docs/using-cli.md

@@ -125,24 +125,3 @@ Please note that
 metadata to be added back to the script. Remove the filter if you want to store Jupytext's settings, or the kernel information, in the text file.
 - Cell metadata are available in the `light` and `percent` formats, as well as in the Markdown and R Markdown formats. R scripts in `spin` format support cell metadata for code cells only. Sphinx Gallery scripts in `sphinx` format do not support cell metadata.
 - By default, a few cell metadata are not included in the text representation of the notebook. And only the most standard notebook metadata are exported. Learn more on this in the sections for [notebook specific](using-server.html#per-notebook-configuration) and [global settings](using-server.html#metadata-filtering) for metadata filtering.
-
-## Reading notebooks in Python
-
-Jupytext provides the same `read`, `write`, `reads` and `writes` functions as `nbformat`. You can use `jupytext`'s functions as drop-in replacements for `nbformat`'s ones. Jupytext's implementation provides an additional `fmt` argument, which can be any of `py`, `md`, `jl:percent`, etc. If not explicitly provided, the argument is inferred from the file extension.
-
-```python
-import jupytext
-
-# Read a notebook from a file 
-jupytext.read('notebook.md')
-
-# Read a notebook from a string
-jupytext.reads(text, fmt='md')
-
-# Return the text representation of a notebook
-jupytext.writes(notebook, fmt='py:percent')
-
-# Write a notebook to a file in the desired format
-jupytext.write(notebook, 'notebook.py')
-jupytext.write(notebook, 'notebook.py', fmt='py:percent')
-```

docs/using-library.md

@@ -0,0 +1,45 @@
+# Using the Jupytext Python library
+
+Jupytext provides the same `read`, `write`, `reads` and `writes` functions as `nbformat`.
+You can use `jupytext`'s functions as drop-in replacements for `nbformat`'s ones.
+
+## Reading notebooks from many text formats
+
+To read text files as notebooks, simply provide the path to a Jupytext-supported
+format.
+```python
+import jupytext
+
+# Read a notebook from a file 
+ntbk = jupytext.read('notebook.md')
+
+# Read a notebook from a string
+jupytext.reads(text, fmt='md')
+```
+
+Jupytext will read in the content and infer metadata about the file
+from the YAML header (if there is one). If there is no Jupytext header,
+then Jupytext will make some assumptions about the format based on the
+file extension.
+
+This function returns an instance of an `nbformat` `NotebookNode`. You
+can find more information for working with this notebook representation
+in the [nbformat documentation](https://nbformat.readthedocs.io).
+
+## Writing notebooks to many text files
+
+You can also write in-memory notebooks to a variety of text formats by
+using `jupytext.write`.
+
+Jupytext's implementation provides an additional `fmt` argument,
+which can be any of the accepted Jupytext extensions (e.g., `py`, `md`, `jl:percent`)
+If not explicitly provided, the argument is inferred from the file extension.
+
+```python
+# Return the text representation of a notebook
+jupytext.writes(notebook, fmt='py:percent')
+
+# Write a notebook to a file in the desired format
+jupytext.write(notebook, 'notebook.py')
+jupytext.write(notebook, 'notebook.py', fmt='py:percent')
+```