-
Notifications
You must be signed in to change notification settings - Fork 200
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
21 changed files
with
2,333 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Minimal makefile for Sphinx documentation | ||
# | ||
|
||
# You can set these variables from the command line, and also | ||
# from the environment for the first two. | ||
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) |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,56 @@ | ||
# 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: | ||
# https://www.sphinx-doc.org/en/master/usage/configuration.html | ||
|
||
# -- 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 = "MyST-NB" | ||
copyright = "2020, Executable Book Project" | ||
author = "Executable Book Project" | ||
|
||
master_doc = "index" | ||
|
||
# -- 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 = ["myst_parser", "myst_nb"] | ||
|
||
# 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", "**.ipynb_checkpoints"] | ||
|
||
|
||
# -- 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_book_theme" | ||
html_logo = "_static/logo.png" | ||
html_title = "Sphinx Book Theme" | ||
# html_theme_options = {"github_url": "https://github.com/ExecutableBookProject/myst-nb"} | ||
|
||
# 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"] | ||
jupyter_sphinx_require_url = "" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
# Features | ||
|
||
This section covers some of the main features in Jupyter Book. Browse | ||
the chapers to the left to learn more about what you can do. | ||
|
||
```{toctree} | ||
myst | ||
notebooks | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,237 @@ | ||
# MyST Markdown | ||
|
||
In addition to CommonMark markdown, Jupyter Book also supports | ||
a special flavor of markdown called **MyST (or | ||
Markedly Structured Text)**. It was designed to make it easier to create | ||
publishable computational documents in Markdown. It is a superset of | ||
[CommonMark markdown](https://commonmark.org/) and draws heavy inspiration | ||
from the fantastic [RMarkdown language from RStudio](https://rmarkdown.rstudio.com/). | ||
|
||
You can write MyST markdown in either markdown files, or in Jupyter Notebooks. | ||
Jupyter Book will know how to parse both of them. | ||
|
||
This page contains a few pieces of information about MyST markdown and how it | ||
relates to Jupyter Book. You can | ||
find much more information about this flavor of markdown at | ||
[The Myst Parser documentation][myst-parser]. | ||
|
||
```{note} | ||
Roles and directives are two of the most powerful tools in Jupyter Book. They | ||
are kind of like *functions*, but written in a markup language. They both | ||
serve a similar purpose, but **roles are written in one line**, whereas | ||
**directives span many lines**. They both accept different kinds of inputs, | ||
and what they do with those inputs depends on the specific role or directive | ||
that is being called. | ||
``` | ||
|
||
Whether you write your book's content in Jupyter Notebooks (`.ipynb`) or | ||
in regular markdown files (`.md`), you'll write in the same flavor of | ||
**MyST Markdown**. | ||
|
||
## Directives | ||
|
||
Directives customize the look, feel, and behavior of your book. They are | ||
kind of like *functions*, and come in a variety of names | ||
with different behavior. This section covers how to structure and use them. | ||
|
||
### Using a directive | ||
|
||
At its simplest, you can insert a directive into your book's content like so: | ||
|
||
```` | ||
```{mydirectivename} | ||
My directive content | ||
``` | ||
```` | ||
|
||
This will only work if a directive with name `mydirectivename` already exists | ||
(which it doesn't). There are many pre-defined directives associated with | ||
Jupyter Book. For example, to insert a note box into your content, you can | ||
use the following directive: | ||
|
||
```` | ||
```{note} | ||
Here is a note | ||
``` | ||
```` | ||
|
||
This results in: | ||
|
||
```{note} | ||
Here is a note | ||
``` | ||
|
||
In your built book. | ||
|
||
For more information on writing directives, see the | ||
[MyST documentation](https://myst-parser.readthedocs.io/). | ||
|
||
### More arguments and metadata in directives | ||
|
||
Many directives allow you to control their behavior with extra pieces of | ||
information. In addition to the directive name and the directive content, | ||
directives allow two other configuration points: | ||
|
||
* **directive arguments** - are a list of words that come just after the | ||
`{directivename}` is given. | ||
* **directive metadata** - is a collection of flags or key/value pairs | ||
that come just underneath `{directivename}`. This has two forms: either | ||
YAML metadata, or `:key: val` pairs. | ||
|
||
Here's what directives with all of their configuration points look like: | ||
|
||
```` | ||
```{directivename} directive arguments | ||
--- | ||
metadata1: metadata2 | ||
metadata3: metadata4 | ||
--- | ||
My directive content. | ||
``` | ||
```` | ||
|
||
or: | ||
|
||
```` | ||
```{directivename} directive arguments | ||
:key1: metadata1 | ||
:key2: metadata2 | ||
``` | ||
My directive content. | ||
```` | ||
|
||
For examples of how this is used, see the sections below. | ||
|
||
## Roles | ||
|
||
Roles are very similar to directives, but they are less-complex and written | ||
entirely on one line. You can insert a role into your book's content with | ||
this pattern: | ||
|
||
``` | ||
Some content {rolename}`and here is my role's content!` | ||
``` | ||
|
||
Again, roles will only work if `rolename` is a valid role's name. For example, | ||
the `doc` role can be used to refer to another page in your book. You can | ||
refer directly to another page by its relative path. For example, the | ||
role syntax `` {doc}`notebooks` `` will result in: {doc}`notebooks`. | ||
|
||
For more information on writing roles, see the | ||
[MyST documentation](https://myst-parser.readthedocs.io/). | ||
|
||
(labels-and-refs)= | ||
## Labels and cross-references | ||
|
||
Labels are a way to add tags to parts of your content that you can reference | ||
later on. This is helpful if you want to quickly insert links to other | ||
parts of your book. Labels can be added before major elements of a page, | ||
such as titles or figures. | ||
|
||
To add a label, use the following pattern **before** the element you wish | ||
to label: | ||
|
||
``` | ||
(my-label)= | ||
# The thing to label | ||
``` | ||
|
||
For example, we've added the following label above the header for this section: | ||
|
||
``` | ||
(labels-and-refs)= | ||
## Labels and cross-references | ||
``` | ||
|
||
You can insert cross-references to labels in your content with the following | ||
syntax: `` {ref}`label-text` ``. For example, the following syntax: | ||
`` {ref}`labels-and-refs` `` results in a link to this section like so: | ||
{ref}`labels-and-refs`. | ||
|
||
|
||
## Figures | ||
|
||
MyST Markdown also lets you include **figures** in your page. Figures are | ||
like images, except that they are easier to reference elsewhere in your | ||
book, and they include things like captions. To include a figure, use this | ||
pattern: | ||
|
||
```` | ||
```{figure} ../images/cool.jpg | ||
--- | ||
height: 150px | ||
--- | ||
Here is my figure caption! | ||
``` | ||
```` | ||
|
||
(my-figure)= | ||
|
||
```{figure} ../images/cool.jpg | ||
--- | ||
height: 150px | ||
--- | ||
Here is my figure caption! | ||
``` | ||
|
||
You can then refer to this figure using {ref}`my-figure`. | ||
|
||
## Special blocks of markdown | ||
|
||
Another common use of directives is to designate "special blocks" of your | ||
content. This section covers a few common ones. | ||
|
||
### Notes and warnings | ||
|
||
Let's say you wish to highlight a particular block of | ||
text that exists slightly apart from the narrative of your page. You can | ||
use the **`{note}`** directive for this. | ||
|
||
For example, the following text: | ||
|
||
```` | ||
```{note} | ||
Here is a note! | ||
``` | ||
```` | ||
|
||
Results in the following output: | ||
|
||
```{note} | ||
Here is a note! | ||
``` | ||
|
||
Another common directive that result in similar output is **`{warning}`**. | ||
|
||
Finally, you can choose the title of your message box by using the | ||
**`{admonition}`** directive. For example, the following text: | ||
|
||
```` | ||
```{admonition} Here's your admonition | ||
Here's the admonition content | ||
``` | ||
```` | ||
|
||
Results in the following output: | ||
|
||
```{admonition} Here's your admonition | ||
Here's the admonition content | ||
``` | ||
|
||
### Sidebar content | ||
|
||
You can also specify content that should exist in the sidebar. This content | ||
will be placed to the right, allowing it to exist separately from your main | ||
content. To add sidebar content, use this syntax: | ||
|
||
```` | ||
```{sidebar} | ||
**Here is my sidebar content**, it is pretty cool! | ||
``` | ||
```` | ||
|
||
```{sidebar} **Here is my sidebar content** | ||
It is pretty cool! | ||
``` | ||
|
||
[myst-parser]: https://myst-parser.readthedocs.io/en/latest/ |
Oops, something went wrong.