Books.jl

Create books with Julia.

CI Testing Code Style: Blue ColPrac: Contributor's Guide on Collaborative Practices for Community Packages

In a nutshell, this package is meant to generate books (or reports or dashboards) with embedded Julia output. Via Pandoc, the package can live serve a website and build various outputs including a website, PDF, and DOCX. For many standard output types, such as DataFrames and plots, the package can run your code and will automatically handle proper embedding in the output documents, and also try to guess suitable captions and labels. Also, it is possible to work via the live server, which shows changes within seconds.

This package assumes that:

  • the user is comfortable with managing two REPLs,
  • the user wants to run Julia code and embed the output in a book,
  • the book (website, PDF and DOCX) is built via CI, and
  • Markdown sections and subsections (level 2) should be numbered and listed in the HTML menu.

The reason that numbering of sections is always assumed is to allow the book to be printed. Without section numbers, it is difficult to refer to other parts of the book.

If you do not want numbered sections, but instead a more dynamic website with links, then checkout Franklin.jl. If you want a small report instead of a book with numbered sections, then Weave.jl might be more suitable for your problem. For smaller projects and a friendlier interface, take a look at Pluto.jl.

Currently, this package is used to write the Julia Data Science book.

Usage

To install this package (Julia 1.6/1.7 on MacOS/Linux), use

pkg> add Books

See, the documentation for more information.

Windows

Currently, this package (probably) does not work on Windows. The fixes should be fairly easy. I simply have to look into it a bit more.

Getting help

If you run into problems when using this package, feel free to open an issue here at GitHub or click this link to ask a question at Discourse. For short questions, feel free to send me a PM at https://julialang.slack.com.