Contents

自动创建书

本节介绍如何自动创建书籍，以便更快地入门。

Create a book from a simple template

Jupyter Book lets you quickly generate a book structure from templates. This section covers the process of creating a template book and building it as an alternative to manually creating the files in your book.

To see your options for creating books from templates, run the following command:

jupyter-book create --help

Usage: jupyter-book create [OPTIONS] PATH_BOOK

  Create a Jupyter Book template that you can customize.

Options:
  --cookiecutter  Use cookiecutter to interactively create a Jupyter Book
                  template.

  -h, --help      Show this message and exit.

This option is best if you are starting from scratch, or would like to see one example of a simple Jupyter Book on your own filesystem.

If you’d just like to quickly create a sample book, you may do so by running the following command:

jupyter-book create mynewbook/

This will generate a mini Jupyter Book that you can both build and explore locally. It will have a few decisions made for you, and you can explore the configuration of the book in _config.yml and its structure in _toc.yml. Use this book as inspiration, or as a starting point to work from.

Create a more complete book from interactive prompts

This option is best if you’d like to answer a few questions from the command line in order to create a template book that is more complex and customized for your use-case.

Jupyter Book also provides a Jupyter Book cookiecutter that can be used to interactively create a book directory structure.

cookiecutter is a Python tool for quickly generating folders from a templatized repository. Jupyter Book uses cookiecutter under the hood.

The cookiecutter is suitable for users that want to create a ready-to-go repository to host their book that includes pre-populated metafiles such as README, LICENSE, CONDUCT, CONTRIBUTING, etc., as well as GitHub Actions workflow files to Automatically host your book with GitHub Actions.

To try the cookiecutter template, run the following command:

jupyter-book create mynewbook/ --cookiecutter

For more help, see the Jupyter Book cookiecutter GitHub repository, or run:

Create book files from a Table of Contents

It is possible to use a _toc.yml file in order to create the skeleton of a book automatically. This is useful if you wish to quickly generate empty files from a single structure, and then populate them with content yourselves.

To create your book’s files from the Table of Contents, use the following command:

jupyter-book toc to-project path/to/_toc.yml

This will generate a collection of files according to the structure in _toc.yml.

In addition, you have a few options to control the behavior of this tool. See below for reference.

Usage: jupyter-book toc to-project [OPTIONS] TOC_FILE

  Create a project directory from a ToC file.

Options:
  -p, --path DIRECTORY      The root directory [default: ToC file directory].
  -e, --extension [rst|md]  The default file extension to use.  [default: rst]
  -o, --overwrite           Overwrite existing files.
  -h, --help                Show this message and exit.