Skip to content

Latest commit

 

History

History
146 lines (102 loc) · 4.8 KB

README.md

File metadata and controls

146 lines (102 loc) · 4.8 KB
Raw

Jupyter Book to HTMLBook

Takes a Jupyter Book and turns it into an HTMLBook-compliant project for consumption in Atlas, O'Reilly's book building tool. The script runs jupyter-book on your book directory (the one containing your _config.yml and _toc.yml files), and puts HTMLBook files in the specified target directory, updating atlas.json if it's provided.

IMPORTANT: We're now at >1.0.0, i.e., we have introduced a very breaking-change from the original version of the script!

Installation

NOTE: This tool requires Python ^3.9.

Install via the GitHub link:

pip install git+https://github.com/oreillymedia/jupyter-book-to-htmlbook.git

Or clone the repository, install poetry (pip install poetry), build the project (poetry build) and then install the locally-build wheel:

pip install dist/jupyter_book_to_htmlbook-X.X.X-py3-none-any.whl

Usage

Usage:jb2htmlbook [OPTIONS] SOURCE TARGET

Help text:

$ jb2htmlbook --help
Usage: jb2htmlbook [OPTIONS] SOURCE TARGET

  Converts a Jupyter Book project into HTMLBook.

  Takes your SOURCE directory (which should contain your _toc and _config
  files), runs `jupyter-book`, converts and consolidates the output to
  HTMLBook, and places those files in the TARGET directory.

  If you for some reason don't want this script to run `jupyter-book` (`jb`),
  use the SKIP_JB_BUILD option.

  If you want to UPDATE_ATLAS_JSON, provide the relative path to the
  atlas.json file (will usually be just "atlas.json")

  Returns a json list of converted "files" as output for consumption by Atlas,
  O'Reilly's in-house publishing tool. Saves run information to
  jupyter_book_to_htmlbook_run.log

Arguments:
  SOURCE  [required]
  TARGET  [required]

Options:
  --atlas-json TEXT               Path to the book's atlas.json file
  --skip-jb-build                 Skip running `jupyter-book` as a part of
                                  this conversion
  --skip-numbering                Skip the numbering of In[]/Out[] code cells
  --include-root                  Include the 'root' file of the jupyter-book
                                  project
  --keep-highlighting             Preserve any code highlighting provided by
                                  Jupyter Book
  --version
  --install-completion [bash|zsh|fish|powershell|pwsh]
                                  Install completion for the specified shell.
  --show-completion [bash|zsh|fish|powershell|pwsh]
                                  Show completion for the specified shell, to
                                  copy it or customize the installation.
  --help                          Show this message and exit.

Current (Known) Limitations

  • Jupyter Book can only process one metadata-named code-generated figure per file. The workaround for this is to save any resultant figures to disk and refer to them as any other figure.

Release Notes

1.1.2

Bug fix:

  • Allow "style" attributes to remain inside SVGs

1.1.1

Bug fix:

  • Don't drop additional top-level headings in subchapter files

1.1.0

Features:

  • Upgrade to Jupyter Book v.0.15.1
  • --keep-highlighting flag to preserve syntax highlighting for code blocks provided by Jupyter Book

Bug fixes:

  • Table caption numbering is now removed from output (was causing duplicates in Atlas builds)
  • Additional safeguards around figure markup
  • Generated part.html files now have correctly-numbered (and unique) IDs

Quality of life improvements:

  • Explicit tests for common PE tasks
  • Additional examples in the example_book
  • Improved type hints

1.0.9

Bug fixes:

  • Remove spans inside <code> tags that display incorrectly on the ORM learning platform

1.0.8

Bug fixes:

  • Part caption casing is preserved from _toc.yaml

1.0.7

Features:

  • Add support for formal code examples in Python and R via the "example" cell tag
  • Add support for glossaries
  • Add basic support for bibtex bibliographies
  • Align sidebar heading levels with changes in Atlas

Bug fixes:

  • Fix bug with top-level heading IDs causing xrefs to fail
  • Remove extraneous spacing in figure captions
  • Remove epub-breaking attrs (incl. valign and halign on table cells)

1.0.6

1.0.1 - 1.0.5

  • Add support for R via rpy2 syntax in Notebooks
  • Further quiet jb build to support Atlas builds
  • Dependency security version updates
  • Better code block handling, including In[]/Out[]
  • Duplicate IDs are now removed programmatically globally in the book

1.0.0

  • First release with CLI interface
  • Supports automatically updating the atlas.json file with the list of converted jupyter book files

0.1.0 (untagged)

  • First poetry version

0.0.0

  • Initial conversion script targeted at a specific project.