Making books#

Summary#

System	Valid input files	Compatibility with Python & R	Blog posts (tags, dates, filters) ?	Nice examples	Additional details
Jupyter Book Documentation	- Markdown `.md` - Jupyter notebook `.ipynb` - MyST markdown notebook `.md` - reStructured Text `.rst` (not recommended) [source]	Python tool. Would probably only use with R if you were working with R in `.ipynb`. Possible to convert `.Rmd` to `ipynb` or MyST	Not found example	SAMueL-1 SAMueL-2	Easy integration with BinderHub and Google Colab [source] Uses Sphinx to build book [source]
Sphinx Documentation	- reStructured Text `.rst` (default) - Markdown `.md` - Jupyter notebook `.ipynb` (with nbsphinx and MyST-NB)	Designed for Python, didn’t easily run into R implementation, but examples here in various languages	Yes	pyOpenSci Little book of R for biomedical statistics Chris Holdgraf’s blog	Thumbnail gallery, Binder, nbviewer [source]
Quarto Documentation	- Cross-language Quarto markdown `.qmd` (which combines markdown and executable code) -Jupyter notebook `.ipynb` - Markdown `.md` - R markdown `.Rmd` [source]	Explicitly supports dynamic content from Python, R, Julia and Observable [source] Comparison with Rmd	Well supported natively Tutorial 1 Tutorial 2 Tutorial 3	ddanieltan’s blog Quarto’s blog - github, site R for Data Science Python for Data Analysis HSMA DES Book - github, site	Huge range of supported output formats [source]
Jekyll	- Markdown `.md` - HTML	Written in Ruby. Creates simple static sites.		Exeter RSE Workshop - github, site Ruby’s website
Mkdocs Documentation	- Markdown `.md` Seems possible for others but more designed for markdown?	Designed for Python	Yes with Material for Mkdocs plugin	Material for MkDocs - github, site Cookiecutter Data Science - github, site	Material for MkDocs provides additional features
Bookdown Documentation	- R Markdown `.Rmd`	Designed for R		R Markdown Definitive Guide R Markdown Cookbook
Blogdown Documentation	- R Markdown `.Rmd`	Designed for R		List of blogs	Built on Hugo [source]
Hugodown Documentation	- R Markdown `.Rmd`	Designed for R		List of blogs	Built on Hugo
Distill for R Markdown Documentation	- R Markdown `.Rmd`	Designed for R	Yes natively (eg. set up project as blog or website)	Piping Hot Data Tidy models Before I sleep

Reflections on RMarkdown, Distill, Bookdown and Blogdown.

Paid: https://www.gitbook.com/pricing

Other random noted down options not explored:

Sandpaper, pegboard and varnish - example: https://carpentries-lab.github.io/good-enough-practices/index.html
Sweave/LaTeX RStudio/LaTeX Pandoc SageMath Colab Notebooks Nbconvert Pelican Org mode DocOnce Scribus Madoko Texinfo

Quarto#

Getting set up…

Install Quarto - https://quarto.org/docs/get-started/ - I downloaded the Linux deb file, then ran sudo dpkg -i packagename.deb
Create environment with necessary requirements (this may not be a necessary step, but this is what I decided to do) - for me, I needed:

ipykernel
pyyaml
nbformat
nbclient

Install Quarto VS Code extension (and then perhaps open and close VS Code)
Within VS Code, Ctrl+Shift+P > Quarto: Create Project
Ctrl+Shift+P > Select Interpreter > choose the environment created

Render full .qmd: Ctrl+Shift+K

Render file: quarto render hello.qmd --to html

Render to alt. output: quarto render hello.qmd --to docx

Run individual cells by selecting the Run Cell button.

You’ll see there’s a few Quarto projects that pop up -

Basic
Book
Blog
Manuscript
Website

A book is actually a special type of website - the most important difference is that it uses chapter numbers and supports cross-references between different chapters. [source]

For a blog, the posts are in seperate pages as the filename has to be index.qmd.

To change preview type when using VSCode to preview, go to Settings > Quarto > Render: Preview Type and set to external

Commands to check/make/preview book:

quarto check - checks if would build successfully
quarto preview - previews as-is
quarto render - rebuilds whole book
quarto preview button in VS code - will render current page, and will render other pages when you click on them, except blog posts

Jupyter book#

Install jupyter-book package.

To create sample book stored in current location: jupyter-book create book_name/

To build/rebuild book: jupyter-book build book_name

If add new page and book table of contents doesn’t update upon rebuild, try: jupyter-book build --all book_name

Sphinx#

Note: Written for package documentation

To convert from Jupyter book to sphinx, run: jupyter-book config sphinx path/to/book. This will generate a conf.py file from your _config.yml and _toc.yml files. You can then run `sphinx-build path/to/book path/to/book/_build/html -b html.

Add to environment:
- sphinx
- sphinx-rtd-theme
- myst-parser
- sphinx-autoapi
Create directory called docs and enter it - e.g. mkdir docs and cd docs.
Add/create any files you want to include in the docs (e.g. how to guides, descriptions) - can be markdown or rst - e.g. guide1.md and guide2.md
Run sphinx-quickstart
Modify index.rst file - this is used as home page - e.g.

Documentation for package name
==============================

This package...

.. note::

   This project is under active development.

If you don’t want toctree within the home page, and just want it to be in the sidebar, then produce a contents.rst - e.g.

Site contents
*************

.. toctree::

   Home <index>
   guide1
   guide2

Modify conf.py - e.g.

# -- General configuration ---------------------------------------------------

extensions = [
    'myst_parser',  # To use markdown as well as reStructuredText
    'autoapi.extension'  # Auto generate module and function documentation
]

# Location of files for auto API
autoapi_dirs = ['../kailo_beewell_dashboard']

# File types for documentation
source_suffix = ['.rst', '.md']

templates_path = ['_templates']

# Location of toctree
master_doc = 'contents'

exclude_patterns = ['_build', '_templates', 'Thumbs.db', '.DS_Store']

language = 'English'

# -- Options for HTML output -------------------------------------------------

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

Produce the documentation. Any time you want to do this, from the docs folder, run:
- make clean (to clear out build folder, else might not update everything fully)
- make html