genai

booooook

This file will become your README and also the index of your documentation.

Setup

I’ve set up pre-commit to check staged changes and make sure notebooks are cleaned and export nicely. If you install the nbdev hooks (nbdev_install_hooks) and edit with jupyter notebooks or jupyter lab this should never be an issue, if you edit with VS code or something you may have to run nbdev_clean and nbdev_export before commiting changes. To set things up, in this folder run:

pip install nbdev pre-commit
nbdev_install_hooks
pre-commit install

The book will be written as notebooks in the nbs folder. This readme is generated from index.ipynb.

I recommend running nbdev_preview to see a rendered preview of the contents in the browser, which will update any time you save changes to a notebook.

Export

We can render the notebooks to ASCIIDOC with quarto render nbs -t asciidoc --output-dir /path/to/output/folder.

You can also run quarto install tinytex to install LaTeX and then quarto render nbs -t pdf --output-dir /path/to/output/folder to render the notebooks to PDFs.

To check the ASCIIDOC output, install asciidoctor (sudo apt install ruby-asciidoctor-pdf or follow https://docs.asciidoctor.org/pdf-converter/latest/install/) then https://quarto.org/docs/prerelease/1.3/asciidoc-books.html#previewing-asciidoc-content.

For previewing a single chapter, I do quarto render nbs/01_04_diffusion_models_intro.ipynb --to asciidoc --output-dir ~ then convert to PDF with asciidoctor-pdf 01_04_diffusion_models_intro.txt.

Pushing a new chapter to atlas

Create an SSH key: https://docs.atlas.oreilly.com/using_git.html#sshkeys

Add to account (account settings)

Clone the repo: git -c core.sshCommand="ssh -i ~/.ssh/id_rsa" clone git@git.atlas.oreilly.com:oreillymedia/hands-on-generative-ai-with-transformers-and-diffusion-models.git

Add asciidoc file (rename .txt to .asciidoc) and folder of images

Add the filename in “files” section of atlas.json

Commit and push

Style Guide

At the start of each notebook, add a markdown cell with the overall heading / chapter title (eg # Diffusion Models).

Subsections should be ## (eg ## Iterative Refinement) and they can have ### headings within them.

Code cells should be formatted with #hide if you don’t want them to appear in the docs.

Imports should get their own cell or cells rather than being mixed with code

You can #|hide cells with boilerplate for showing images, etc. to keep only the relevant code included in the rendered content.

To hide the code but show the output, use #|echo: false.

To hide the output but show the code, use #|output: false.

To make callout sections, use:

::: {.callout-note} 
Your callout text here 
:::

Which won’t render in Jupyter but will show up in the document:

Note

Your callout text here, can be note, tip, warning, caution and important

Important

This is an important callout

Important Links

TODO fill in links to schedule, relevant docs from O’Reilly etc

Original proposal with TOC (not final): https://docs.google.com/document/d/1oUYBpP5i1BOvEczssGjeM-FMroykJB9qg4WadZI1Xck/edit#

Help docs, writing resources, and author guidelines (from Jill):

Brief author guidelines as well as a sample preface are attached to this email

Here is a link to the O’Reilly author portal, where you can edit your profile and eventually view sales data and manage errata: https://app.oreilly.com/authors/resources.csp. The section on the welcome page about writing multi-authored books may be particularly helpful.

Here’s a link to a project planning doc to help keep things on schedule: https://docs.google.com/spreadsheets/d/1H2Of3VqEhzvF6xTuejgP3Tr2TXP6ZVfBs_GDU1AX3vg/edit?usp=sharing

Here are our Atlas help docs: http://docs.atlas.oreilly.com/

Here’s a guide to writing in asciidoc: http://docs.atlas.oreilly.com/writing_in_asciidoc.html. I’ve also attached an asciidoc sample.

Information on our House Style Guide can be found here: http://oreillymedia.github.io/production-resources/styleguide/

Here’s a link to our illustration and screenshot guidelines. I’ve also attached a one-sheet illustration guide. Our team will redraw line art for harmonized images throughout your book.

Additional information on our house style and redraw process can be accessed here: https://github.com/oreillymedia/production-resources/blob/gh-pages/illustrations/orm_illustration_examples.png

Here is info on permissions: http://oreillymedia.github.io/production-resources/permissionsandfairuseguide/

If you have any questions about Atlas or asciidoc, you can email our Atlas help team directly at toolsreq@oreilly.com

Please fill out a figure log as you write (here’s a template), listing all images by number and letting us know what you’d like to have redrawn in production.

I believe you already have an account for free access to O’Reilly’s learning platform,and you should receive an email from our team soon. If you have any trouble accessing the platform, please just let me know.

If you need hard copies of an O’Reilly book to help with your research, I can send that as well.