Skip to content

Commit a0df6ff

Browse files
choldgrafcholdgraf
committed
adding docs and a demo template
1 parent 9e52085 commit a0df6ff

16 files changed

+443
-35
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ instance/
7070

7171
# Sphinx documentation
7272
docs/_build/
73+
jupyter_book/book_template/_build
7374

7475
# PyBuilder
7576
target/

‎docs/toc.yml ‎docs/_toc.yml

File renamed without changes.

‎docs/guide/01-5_tour.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ the pieces that you'll modify for your own book.
77
To create a **demo Jupyter Book** to use as a template, run the following command:
88

99
```bash
10-
jupyter-book create mybookname --demo
10+
jb create mybookname --demo
1111
```
1212

1313
A new book will be created at the path that you've given (in this case, `mybookname/`).
@@ -96,9 +96,9 @@ file in your `content/` folder. Here's an example of a few pages defined in `toc
9696
9797
The top-most level of your TOC file are **book chapters**. Above, this is the
9898
"Features" page.
99-
Note that in this case the title of the page is not explicitly specified but
99+
Note that in this case the title of the page is not explicitly specified but
100100
is inferred from the source files.
101-
This behavior is controlled by the `page_titles` setting in `_config.yml`
101+
This behavior is controlled by the `page_titles` setting in `_config.yml`
102102
(see [the titles feature page](../features/titles) for more details).
103103
Each chapter can have
104104
several sections (defined in `sections:`) and each section can have several sub-sections

‎docs/guide/01_overview.md

+21-24
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,37 @@
11
# The Jupyter Book Guide
22

3-
This is a guide for creating your own book using
4-
Jupyter Notebooks and Jekyll. Book content is written in markdown and
5-
Jupyter Notebooks, and `jupyter-book` converts these into
6-
a book fit for hosting on the web.
3+
This is a guide for creating your own book using Jupyter Book.
4+
Book content is written in markdown and Jupyter Notebooks, and
5+
`jupyter-book` converts these into a book fit for hosting on the web or a
6+
publishable PDF.
77

88
## Install the command-line interface
99

1010
First off, make sure you have the CLI installed so that you can work with Jupyter Book.
11-
The Jupyter-Book CLI allows you to create, build, upgrade, and otherwise control your
11+
The Jupyter-Book CLI allows you to build and control your
1212
Jupyter Book. You can install it via pip with the following command:
1313

1414
```bash
15-
pip install jupyter-book
15+
pip install git+https://github.com/ExecutableBookProject/cli.git@master
1616
```
1717

1818
## The book building process
1919

20-
Building a Jupyter Book broadly consists of three steps:
21-
22-
1. **Create your book template**. Jupyter Book expects a particular
23-
collection of files and folders that work with the Static Site Generator
24-
Jekyll. The [anatomy of a Jupyter Book](01-5_tour) section covers the
25-
general structure of Jupyter Books, and the [create your book template](02_create)
26-
guide shows how to create your own book structure.
27-
2. **Convert each page of your book into HTML**. We first create each page of
28-
your book into HTML. This converts your `.ipynb`, `.md`, etc files into HTML
29-
that can be understood by a website. It also uses your book's metadata to insert
30-
tags and other layout elements into each page's HTML. See the [building each page's HTML](03_build)
31-
section for more information.
32-
3. **Build your book's HTML from these pages**. Once we have HTML for each page, we
33-
can stitch them together for a book. At the end of this step, you should have
34-
standalone HTML that can be hosted online. See the [build your book's html](publish/book-html)
35-
section for more information.
36-
4. **Host your book's HTML online**. Once your book's HTML is built, you can host
37-
it online as a public website. This guide [covers a few ways to do this](04_publish).
20+
Building a Jupyter Book broadly consists of two steps:
21+
22+
1. **Put your book content in a folder**. Jupyter Book needs the following
23+
pieces in order to build your book:
24+
25+
* Your content files (the pages of your book) in either markdown or Jupyter
26+
Notebooks.
27+
* A Table of Contents `YAML` file (`_config.yaml`) that defines
28+
the structure of your book.
29+
* (optional) A configuration file (`_config.yml`) to control the behavior
30+
of Jupyter Book.
31+
2. **Build your book**. Using Jupyter Book's command-line interface you can
32+
convert your pages into either an HTML or a PDF book.
33+
3. **Host your book's HTML online**. Once your book's HTML is built, you can host
34+
it online as a public website. See {ref}`04_publish` for more information.
3835

3936
To begin, check out the next section. You can follow this guide linearly, or use it as
4037
a reference later on.

‎docs/intro.md

+47-4
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,57 @@
1-
# Books with Jupyter
1+
# Books with Jupyter 2.0
2+
3+
```{warning}
4+
This is an early prototype tool that may evolve quickly. Your feedback is
5+
very welcome! To give it, please [open an issue in the CLI repository](https://github.com/ExecutableBookProject/cli/issues/new)
6+
```
7+
8+
This tool provides a command-line interface and a Python API that lets users
9+
do the following:
10+
11+
* Write their content in markdown files, Jupyter Notebooks, or rST files.
12+
* Include computational elements in any of the above (e.g. executable
13+
code cells along with their outputs)
14+
* Include rich syntax for publication features, such as citations,
15+
cross-references, and equations.
16+
* Using a simple command, convert this content into:
17+
* A web-based interactive book
18+
* A publication-quality PDF
19+
20+
Currently it accomplishes a subset of these features.
221

322
## Install
423

24+
Install this tool directly from the Master branch. When it has stabilized
25+
we will begin creating releases.
26+
27+
```
28+
pip install git+https://github.com/ExecutableBookProject/cli.git@master
29+
```
30+
31+
## Develop
32+
33+
First clone the package:
34+
35+
```
36+
git clone https://github.com/ExecutableBookProject/cli
37+
cd cli
38+
```
39+
40+
Next, install:
41+
542
```
643
pip install -e .
744
```
845

946
## Use
1047

48+
The primary way to use this tool is via the command line. It provides a
49+
top-level command called `jb`, and a number of sub-commands. Run `jb -h` for
50+
more information.
51+
52+
```{note}
53+
In the future this will probably be renamed to `jupyter-book`, but it remains
54+
`jb` for now to avoid confusion with the current `jupyter-book` project.
1155
```
12-
cd docs
13-
jb build
14-
```
56+
57+
For more information on how to use this tool, see {ref}`guide/01_overview`.

‎jupyter_book/book_template/_config.yml

+84
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
#######################################################################################
2+
# Book settings
3+
title: Jupyter Book
4+
author: The Jupyter Book Community
5+
email: [email protected]
6+
description: >- # this means to ignore newlines until "baseurl:"
7+
This is an example book built with Jupyter Books.
8+
9+
baseurl: "" # the subpath of your site, e.g. /blog. If there is no subpath for your site, use an empty string ""
10+
url: "https://jupyterbook.org" # the base hostname & protocol for your site, e.g. http://example.com
11+
html_logo: images/logo.png
12+
13+
#######################################################################################
14+
# Jupyter Book settings
15+
16+
# Main page settings
17+
footer_text : This page was created by <a href="https://github.com/jupyter/jupyter-book/graphs/contributors">The Jupyter Book Community</a>
18+
19+
# Sidebar settings
20+
show_sidebar : true # Show the sidebar. Only set to false if your only wish to host a single page.
21+
collapse_inactive_chapters: true # Whether to collapse the inactive chapters in the sidebar
22+
collapse_inactive_sections: true # Whether to collapse the sub-sections within a non-active section in the sidebar
23+
textbook_logo : images/logo/logo.png # A logo to be displayed at the top of your textbook sidebar. Should be square
24+
textbook_logo_link : https://jupyterbook.org/intro.html # A link for the logo.
25+
sidebar_footer_text : 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>'
26+
number_toc_chapters : true # Whether to add numbers to chapterse in your Table of Contents. If true, you can control this at the Chapter level in _data/toc.yml
27+
28+
# Search settings
29+
search_max_words_in_content : 100 # In the search function, use at most this many words (too many words will make search slow)
30+
31+
# Controlling page information
32+
page_titles : infer # Either `None`, `infer`, or `toc`
33+
page_authors : None # Either `None` or `infer`
34+
filename_title_split_character : '_' # If inferring titles based on filename, splt on this character.
35+
36+
# Math settings
37+
number_equations : false # Whether to automatically number all block equations with MathJax
38+
39+
#######################################################################################
40+
# Interact link settings
41+
42+
# General interact settings
43+
use_jupyterlab : false # If 'true', interact links will use JupyterLab as the interface
44+
45+
# Jupyterhub link settings
46+
use_jupyterhub_button : false # If 'true', display a button that will direct users to a JupyterHub (that you provide)
47+
jupyterhub_url : "" # The URL for your JupyterHub. If no URL, use ""
48+
jupyterhub_interact_text : "Interact" # The text that interact buttons will contain.
49+
50+
# Binder link settings
51+
use_binder_button : true # If 'true', add a binder button for interactive links
52+
binderhub_url : "https://mybinder.org" # The URL for your BinderHub. If no URL, use ""
53+
binder_repo_base : "https://github.com/" # The site on which the textbook repository is hosted
54+
binder_repo_org : "jupyter" # The username or organization that owns this repository
55+
binder_repo_name : "jupyter-book" # The name of the repository on the web
56+
binder_repo_branch : "gh-pages" # The branch on which your textbook is hosted.
57+
binderhub_interact_text : "Interact" # The text that interact buttons will contain.
58+
59+
# Thebelab settings
60+
use_thebelab_button : true # If 'true', display a button to allow in-page running code cells with Thebelab
61+
thebelab_button_text : "Thebelab" # The text to display inside the Thebelab initialization button
62+
codemirror_theme : "abcdef" # Theme for codemirror cells, for options see https://codemirror.net/doc/manual.html#config
63+
64+
# nbinteract settings
65+
use_show_widgets_button : true # If 'true', display a button to allow in-page running code cells with nbinteract
66+
67+
# Download settings
68+
use_download_button : true # If 'true', display a button to download a zip file for the notebook
69+
download_button_text : "Download" # The text that download buttons will contain
70+
download_page_header : "Made with Jupyter Book" # A header that will be displayed at the top of and PDF-printed page
71+
72+
#######################################################################################
73+
# Jupyter book extensions and additional features
74+
75+
# Bibliography and citation settings. See https://github.com/inukshuk/jekyll-scholar#configuration for options
76+
scholar:
77+
style: apa
78+
79+
#######################################################################################
80+
# Option to add a Goggle analytics tracking code
81+
82+
# Navigate to https://analytics.google.com, add a new property for your jupyter book and copy the tracking id here.
83+
google_analytics:
84+
mytrackingcode: UA-52617120-7

‎jupyter_book/book_template/_toc.yml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
- path: intro
2+
- path: content
3+
sections:
4+
- path: markdown
5+
- path: notebooks
6+
- path: syntax

‎jupyter_book/book_template/content.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Content in Jupyter Book
2+
=======================
3+
4+
There are many ways to write content in Jupyter Book. This short section
5+
covers a few tips for how to do so.

‎jupyter_book/book_template/intro.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Welcome to your Jupyter Book
2+
============================
3+
4+
This is a small sample book to give you a feel for how book content is
5+
structured.
6+
7+
Check out the content pages bundled with this sample book to get started.

‎jupyter_book/book_template/markdown.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Markdown files
2+
==============
3+
4+
Jupyter Book allows you to write your content directly in markdown files.
5+
If you'd like to include computational content with these markdown files,
6+
use the following directive:
7+
8+
````
9+
```{execute}
10+
print("Here is some code to execute")
11+
```
12+
````
13+
14+
When your book is build, the contents of any `{execute}` blocks will be
15+
executed with your default Jupyter kernel, and their outputs will be displayed
16+
in-line with the rest of your content.
17+
18+
For more information about executing computational content with Jupyter Book,
19+
see [The MyST-NB documentation](https://myst-nb.readthedocs.io/).

0 commit comments

Comments
 (0)