From f7b2575f5d4bf38341475009edd0850e88cd81e9 Mon Sep 17 00:00:00 2001 From: Marc Wouts Date: Tue, 4 Jun 2019 14:03:44 +0200 Subject: [PATCH] Fixed links --- docs/examples.md | 8 ++++---- docs/install.md | 2 +- docs/using-cli.md | 6 +++--- docs/using-server.md | 8 ++++---- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/examples.md b/docs/examples.md index fd9226865..5ea5c6f27 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,8 +1,8 @@ -# Example usage +# 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](#paired-notebooks) an `.ipynb` representation, save and share your research as either a plain script or as a traditional Jupyter notebook with outputs. +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 @@ -10,7 +10,7 @@ With Jupytext, collaborating on Jupyter notebooks with Git becomes as easy as co The setup is straightforward: - Open your favorite notebook in Jupyter notebook -- [Associate](#paired-notebooks) a `.py` representation (for instance) to that 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: @@ -27,7 +27,7 @@ In the animation below we propose a quick demo of Jupytext. While the example re - 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](#jupytext-menu-in-jupyter-notebook) in Jupyter Notebook, or in the [Jupytext commands](#jupytext-commands-in-jupyterlab) in JupyterLab. This has the effect of adding a `"jupytext": {"formats": "ipynb,py:light"},` entry to the notebook metadata. +- 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. diff --git a/docs/install.md b/docs/install.md index 13180c69d..83857741d 100644 --- a/docs/install.md +++ b/docs/install.md @@ -26,7 +26,7 @@ If you don't have the notebook icon on text documents after a fresh restart of y ```python c.NotebookApp.contents_manager_class = "jupytext.TextFileContentsManager" ``` -to your `.jupyter/jupyter_notebook_config.py` file (generate a Jupyter config, if you don't have one yet, with `jupyter notebook --generate-config`). Our contents manager accepts a few options: default formats, default metadata filter, etc — read more on this [below](#global-configuration). Then, restart Jupyter Notebook or JupyterLab, either from the JupyterHub interface or from the command line with +to your `.jupyter/jupyter_notebook_config.py` file (generate a Jupyter config, if you don't have one yet, with `jupyter notebook --generate-config`). Our contents manager accepts a few options: default formats, default metadata filter, etc — read more on this [below](using-server.html#global-configuration). Then, restart Jupyter Notebook or JupyterLab, either from the JupyterHub interface or from the command line with ```bash jupyter notebook # or lab ``` diff --git a/docs/using-cli.md b/docs/using-cli.md index 2bf344888..d5a34f4de 100644 --- a/docs/using-cli.md +++ b/docs/using-cli.md @@ -1,4 +1,4 @@ -# Using Jupytext with the command line +# Using Jupytext at the command line ## Command line conversion @@ -69,10 +69,10 @@ jupytext --test --update notebook.ipynb --to py:percent Note that `jupytext --test` compares the resulting notebooks according to its expectations. If you wish to proceed to a strict comparison of the two notebooks, use `jupytext --test-strict`, and use the flag `-x` to report with more details on the first difference, if any. Please note that -- Scripts opened with Jupyter have a default [metadata filter](#default-metadata-filtering) that prevents additional notebook or cell +- Scripts opened with Jupyter have a default [metadata filter](using-server.html#metadata-filtering) that prevents additional notebook or cell 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](#-per-notebook-configuration) and [global settings](#default-metadata-filtering) for metadata filtering. +- 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 diff --git a/docs/using-server.md b/docs/using-server.md index 7ce1c2e66..632e5da72 100644 --- a/docs/using-server.md +++ b/docs/using-server.md @@ -1,4 +1,4 @@ -# Using Jupytext from within Jupyter +# Using Jupytext in Jupyter ## Paired notebooks @@ -6,7 +6,7 @@ Jupytext can write a given notebook to multiple files. In addition to the origin ## Per-notebook configuration -Select the pairing for a given notebook using either the [Jupytext menu](#jupytext-menu-in-jupyter-notebook) in Jupyter Notebook, or the [Jupytext commands](#jupytext-commands-in-jupyterlab) in JupyterLab. +Select the pairing for a given notebook using either the [Jupytext menu](install.html#jupytext-menu-in-jupyter-notebook) in Jupyter Notebook, or the [Jupytext commands](install.html#jupytext-commands-in-jupyterlab) in JupyterLab. These command simply add a `"jupytext": {"formats": "ipynb,md"}`-like entry in the notebook metadata. You could also set that metadata yourself with _Edit/Edit Notebook Metadata_ in Jupyter Notebook. In JupyterLab, use [this extension](https://github.com/yuvipanda/jupyterlab-nbmetadata). @@ -20,7 +20,7 @@ You can pair a notebook to as many text representations as you want (see our _Wo ``` where - `ext` is one of `ipynb`, `md`, `Rmd`, `jl`, `py`, `R`, `sh`, `cpp`, `q`. Use the `auto` extension to have the script extension chosen according to the Jupyter kernel. -- `format_name` (optional) is either `light` (default for scripts), `bare`, `percent`, `hydrogen`, `sphinx` (Python only), `spin` (R only) — see below for the [format specifications](#Format-specifications). +- `format_name` (optional) is either `light` (default for scripts), `bare`, `percent`, `hydrogen`, `sphinx` (Python only), `spin` (R only) — see the [format specifications](formats.md). - `path`, `prefix` and `suffix` allow to save the text representation to files with different names, or in a different folder. If you want to pair a notebook to a python script in a subfolder named `scripts`, set the formats metadata to `ipynb,scripts//py`. If the notebook is in a `notebooks` folder and you want the text representation to be in a `scripts` folder at the same level, set the Jupytext formats to `notebooks//ipynb,scripts//py`. @@ -44,7 +44,7 @@ c.ContentsManager.default_jupytext_formats = "ipynb,md" ``` (and similarly for the other formats). -In case the [`percent`](#the-percent-format) format is your favorite, add the following to your `.jupyter/jupyter_notebook_config.py` file: +In case the [`percent`](formats.html#the-percent-format) format is your favorite, add the following to your `.jupyter/jupyter_notebook_config.py` file: ```python # Use the percent format when saving as py c.ContentsManager.preferred_jupytext_formats_save = "py:percent"