Skip to content

Commit 182d855

Browse files
mdhkmdhk
committed
Update documentation
0 parents  commit 182d855

164 files changed

Lines changed: 12581 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.buildinfo‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: 97465dffce4fd065ec08123eae036377
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎.nojekyll‎

Whitespace-only changes.

‎_sources/intro.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Welcome to your Jupyter Book
2+
3+
This is a small sample book to give you a feel for how book content is
4+
structured.
5+
It shows off a few of the major file types, as well as some sample content.
6+
It does not go in-depth into any particular topic - check out [the Jupyter Book documentation](https://jupyterbook.org) for more information.
7+
8+
Check out the content pages bundled with this sample book to see more.
9+
10+
```{tableofcontents}
11+
```

‎_sources/markdown-notebooks.ipynb‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "e19df04b",
6+
"metadata": {},
7+
"source": [
8+
"# Notebooks with MyST Markdown\n",
9+
"\n",
10+
"Jupyter Book also lets you write text-based notebooks using MyST Markdown.\n",
11+
"See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions.\n",
12+
"This page shows off a notebook written in MyST Markdown.\n",
13+
"\n",
14+
"## An example cell\n",
15+
"\n",
16+
"With MyST Markdown, you can define code cells with a directive like so:"
17+
]
18+
},
19+
{
20+
"cell_type": "code",
21+
"execution_count": null,
22+
"id": "84ff90a3",
23+
"metadata": {},
24+
"outputs": [],
25+
"source": [
26+
"print(2 + 2)"
27+
]
28+
},
29+
{
30+
"cell_type": "markdown",
31+
"id": "c7a863d0",
32+
"metadata": {},
33+
"source": [
34+
"When your book is built, the contents of any `{code-cell}` blocks will be\n",
35+
"executed with your default Jupyter kernel, and their outputs will be displayed\n",
36+
"in-line with the rest of your content.\n",
37+
"\n",
38+
"```{seealso}\n",
39+
"Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html).\n",
40+
"```\n",
41+
"\n",
42+
"## Create a notebook with MyST Markdown\n",
43+
"\n",
44+
"MyST Markdown notebooks are defined by two things:\n",
45+
"\n",
46+
"1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed).\n",
47+
" See the YAML at the top of this page for example.\n",
48+
"2. The presence of `{code-cell}` directives, which will be executed with your book.\n",
49+
"\n",
50+
"That's all that is needed to get started!\n",
51+
"\n",
52+
"## Quickly add YAML metadata for MyST Notebooks\n",
53+
"\n",
54+
"If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command:\n",
55+
"\n",
56+
"```\n",
57+
"jupyter-book myst init path/to/markdownfile.md\n",
58+
"```"
59+
]
60+
}
61+
],
62+
"metadata": {
63+
"jupytext": {
64+
"formats": "md:myst",
65+
"text_representation": {
66+
"extension": ".md",
67+
"format_name": "myst",
68+
"format_version": 0.13,
69+
"jupytext_version": "1.11.5"
70+
}
71+
},
72+
"kernelspec": {
73+
"display_name": "Python 3",
74+
"language": "python",
75+
"name": "python3"
76+
},
77+
"source_map": [
78+
13,
79+
25,
80+
27
81+
]
82+
},
83+
"nbformat": 4,
84+
"nbformat_minor": 5
85+
}

‎_sources/markdown-notebooks.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
jupytext:
3+
formats: md:myst
4+
text_representation:
5+
extension: .md
6+
format_name: myst
7+
format_version: 0.13
8+
jupytext_version: 1.11.5
9+
kernelspec:
10+
display_name: Python 3
11+
language: python
12+
name: python3
13+
---
14+
15+
# Notebooks with MyST Markdown
16+
17+
Jupyter Book also lets you write text-based notebooks using MyST Markdown.
18+
See [the Notebooks with MyST Markdown documentation](https://jupyterbook.org/file-types/myst-notebooks.html) for more detailed instructions.
19+
This page shows off a notebook written in MyST Markdown.
20+
21+
## An example cell
22+
23+
With MyST Markdown, you can define code cells with a directive like so:
24+
25+
```{code-cell}
26+
print(2 + 2)
27+
```
28+
29+
When your book is built, the contents of any `{code-cell}` blocks will be
30+
executed with your default Jupyter kernel, and their outputs will be displayed
31+
in-line with the rest of your content.
32+
33+
```{seealso}
34+
Jupyter Book uses [Jupytext](https://jupytext.readthedocs.io/en/latest/) to convert text-based files to notebooks, and can support [many other text-based notebook files](https://jupyterbook.org/file-types/jupytext.html).
35+
```
36+
37+
## Create a notebook with MyST Markdown
38+
39+
MyST Markdown notebooks are defined by two things:
40+
41+
1. YAML metadata that is needed to understand if / how it should convert text files to notebooks (including information about the kernel needed).
42+
See the YAML at the top of this page for example.
43+
2. The presence of `{code-cell}` directives, which will be executed with your book.
44+
45+
That's all that is needed to get started!
46+
47+
## Quickly add YAML metadata for MyST Notebooks
48+
49+
If you have a markdown file and you'd like to quickly add YAML metadata to it, so that Jupyter Book will treat it as a MyST Markdown Notebook, run the following command:
50+
51+
```
52+
jupyter-book myst init path/to/markdownfile.md
53+
```

‎_sources/markdown.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Markdown Files
2+
3+
Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or
4+
in regular markdown files (`.md`), you'll write in the same flavor of markdown
5+
called **MyST Markdown**.
6+
This is a simple file to help you get started and show off some syntax.
7+
8+
## What is MyST?
9+
10+
MyST stands for "Markedly Structured Text". It
11+
is a slight variation on a flavor of markdown called "CommonMark" markdown,
12+
with small syntax extensions to allow you to write **roles** and **directives**
13+
in the Sphinx ecosystem.
14+
15+
For more about MyST, see [the MyST Markdown Overview](https://jupyterbook.org/content/myst.html).
16+
17+
## Sample Roles and Directives
18+
19+
Roles and directives are two of the most powerful tools in Jupyter Book. They
20+
are like functions, but written in a markup language. They both
21+
serve a similar purpose, but **roles are written in one line**, whereas
22+
**directives span many lines**. They both accept different kinds of inputs,
23+
and what they do with those inputs depends on the specific role or directive
24+
that is being called.
25+
26+
Here is a "note" directive:
27+
28+
```{note}
29+
Here is a note
30+
```
31+
32+
It will be rendered in a special box when you build your book.
33+
34+
Here is an inline directive to refer to a document: {doc}`markdown-notebooks`.
35+
36+
37+
## Citations
38+
39+
You can also cite references that are stored in a `bibtex` file. For example,
40+
the following syntax: `` {cite}`holdgraf_evidence_2014` `` will render like
41+
this: {cite}`holdgraf_evidence_2014`.
42+
43+
Moreover, you can insert a bibliography into your page with this syntax:
44+
The `{bibliography}` directive must be used for all the `{cite}` roles to
45+
render properly.
46+
For example, if the references for your book are stored in `references.bib`,
47+
then the bibliography is inserted with:
48+
49+
```{bibliography}
50+
```
51+
52+
## Learn more
53+
54+
This is just a simple starter to get you started.
55+
You can learn a lot more at [jupyterbook.org](https://jupyterbook.org).

‎_sources/notebooks.ipynb‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Content with notebooks\n",
8+
"\n",
9+
"You can also create content with Jupyter Notebooks. This means that you can include\n",
10+
"code blocks and their outputs in your book.\n",
11+
"\n",
12+
"## Markdown + notebooks\n",
13+
"\n",
14+
"As it is markdown, you can embed images, HTML, etc into your posts!\n",
15+
"\n",
16+
"![](https://myst-parser.readthedocs.io/en/latest/_static/logo-wide.svg)\n",
17+
"\n",
18+
"You can also $add_{math}$ and\n",
19+
"\n",
20+
"$$\n",
21+
"math^{blocks}\n",
22+
"$$\n",
23+
"\n",
24+
"or\n",
25+
"\n",
26+
"$$\n",
27+
"\\begin{aligned}\n",
28+
"\\mbox{mean} la_{tex} \\\\ \\\\\n",
29+
"math blocks\n",
30+
"\\end{aligned}\n",
31+
"$$\n",
32+
"\n",
33+
"But make sure you \\$Escape \\$your \\$dollar signs \\$you want to keep!\n",
34+
"\n",
35+
"## MyST markdown\n",
36+
"\n",
37+
"MyST markdown works in Jupyter Notebooks as well. For more information about MyST markdown, check\n",
38+
"out [the MyST guide in Jupyter Book](https://jupyterbook.org/content/myst.html),\n",
39+
"or see [the MyST markdown documentation](https://myst-parser.readthedocs.io/en/latest/).\n",
40+
"\n",
41+
"## Code blocks and outputs\n",
42+
"\n",
43+
"Jupyter Book will also embed your code blocks and output in your book.\n",
44+
"For example, here's some sample Matplotlib code:"
45+
]
46+
},
47+
{
48+
"cell_type": "code",
49+
"execution_count": null,
50+
"metadata": {},
51+
"outputs": [],
52+
"source": [
53+
"from matplotlib import rcParams, cycler\n",
54+
"import matplotlib.pyplot as plt\n",
55+
"import numpy as np\n",
56+
"plt.ion()"
57+
]
58+
},
59+
{
60+
"cell_type": "code",
61+
"execution_count": null,
62+
"metadata": {},
63+
"outputs": [],
64+
"source": [
65+
"# Fixing random state for reproducibility\n",
66+
"np.random.seed(19680801)\n",
67+
"\n",
68+
"N = 10\n",
69+
"data = [np.logspace(0, 1, 100) + np.random.randn(100) + ii for ii in range(N)]\n",
70+
"data = np.array(data).T\n",
71+
"cmap = plt.cm.coolwarm\n",
72+
"rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))\n",
73+
"\n",
74+
"\n",
75+
"from matplotlib.lines import Line2D\n",
76+
"custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),\n",
77+
" Line2D([0], [0], color=cmap(.5), lw=4),\n",
78+
" Line2D([0], [0], color=cmap(1.), lw=4)]\n",
79+
"\n",
80+
"fig, ax = plt.subplots(figsize=(10, 5))\n",
81+
"lines = ax.plot(data)\n",
82+
"ax.legend(custom_lines, ['Cold', 'Medium', 'Hot']);"
83+
]
84+
},
85+
{
86+
"cell_type": "markdown",
87+
"metadata": {},
88+
"source": [
89+
"There is a lot more that you can do with outputs (such as including interactive outputs)\n",
90+
"with your book. For more information about this, see [the Jupyter Book documentation](https://jupyterbook.org)"
91+
]
92+
}
93+
],
94+
"metadata": {
95+
"kernelspec": {
96+
"display_name": "Python 3",
97+
"language": "python",
98+
"name": "python3"
99+
},
100+
"language_info": {
101+
"codemirror_mode": {
102+
"name": "ipython",
103+
"version": 3
104+
},
105+
"file_extension": ".py",
106+
"mimetype": "text/x-python",
107+
"name": "python",
108+
"nbconvert_exporter": "python",
109+
"pygments_lexer": "ipython3",
110+
"version": "3.8.0"
111+
},
112+
"widgets": {
113+
"application/vnd.jupyter.widget-state+json": {
114+
"state": {},
115+
"version_major": 2,
116+
"version_minor": 0
117+
}
118+
}
119+
},
120+
"nbformat": 4,
121+
"nbformat_minor": 4
122+
}

‎_sphinx_design_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎_sphinx_design_static/design-tabs.js‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
var sd_labels_by_text = {};
2+
3+
function ready() {
4+
const li = document.getElementsByClassName("sd-tab-label");
5+
for (const label of li) {
6+
syncId = label.getAttribute("data-sync-id");
7+
if (syncId) {
8+
label.onclick = onLabelClick;
9+
if (!sd_labels_by_text[syncId]) {
10+
sd_labels_by_text[syncId] = [];
11+
}
12+
sd_labels_by_text[syncId].push(label);
13+
}
14+
}
15+
}
16+
17+
function onLabelClick() {
18+
// Activate other inputs with the same sync id.
19+
syncId = this.getAttribute("data-sync-id");
20+
for (label of sd_labels_by_text[syncId]) {
21+
if (label === this) continue;
22+
label.previousElementSibling.checked = true;
23+
}
24+
window.localStorage.setItem("sphinx-design-last-tab", syncId);
25+
}
26+
27+
document.addEventListener("DOMContentLoaded", ready, false);

0 commit comments

Comments
 (0)