# deep-representation-learning-book: the LaTeX and Python behind an open textbook on representations > The Ma Lab Berkeley repository for Learning Deep Representations of Data Distributions is the source of an open book: LaTeX chapters, runnable experiment code, a make4ht website pipeline and a Chinese translation. This looks at how the pieces are built, and at the parts of the project that are deliberately kept out of the repository. **Ma-Lab-Berkeley/deep-representation-learning-book** — Learning Deep Representations of Data Distributions - Repository: https://github.com/Ma-Lab-Berkeley/deep-representation-learning-book - Website: https://ma-lab-berkeley.github.io/deep-representation-learning-book/ - Stars: 1,105 · Forks: 119 - Language: TeX - License: not declared - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/ma-lab-berkeley-deep-representation-learning-book ## The repository is the source, the PDF is the product The repository for the book Learning Deep Representations of Data Distributions is described in the readme as the source code for the book, and the readme opens by telling most readers that they should not need it. A copy of the book is published as a PDF at the project's own site and is updated periodically. That framing is the key to reading the repository. It is not an application and not a library. It is the working directory of a book: LaTeX sources, the figures they include, the code that produced some of those figures, and the machinery to turn the whole thing into a website. The readme then lists five reasons to clone it, and they map onto five different relationships with the book. You might want to build the book, or one of its chapters, from scratch. You might want the source code that generated a figure. You might want to edit the website. You might want to report that something in the repository does not work. And you might want to contribute content, such as a translation or technical material within a chapter. The project is the Ma Lab at Berkeley, and the published site is at ma-lab-berkeley.github.io. The readme also notes that there is a copy of the book as a PDF that will be updated periodically, which is the practical instruction for a reader who simply wants the book. ## Building the book or a single chapter with latexmk The build requirements for the book are a local `pdflatex` distribution, with TexLive recommended, and a binary of `latexmk`, which ships with TexLive and can alternatively be installed with `brew`. With that in place, the whole book is one command from the repository base folder: ``` latexmk book-main.tex ``` and the output is `book-main.pdf`. Chapters build individually too, which is the workflow that matters for a contributor. To build Chapter 2 you navigate to `chapters/chapter2` and run: ``` latexmk classic-models.tex ``` where `classic-models.tex` is that chapter's file. The readme mentions that some LaTeX hacks were done so that compiling the main book or individual chapters should work inside an IDE, and asks for an issue if it does not. The Chinese translation is built the same way, with one documented caveat. You can do the same with `book-main_zh.tex`, though the readme warns that you may need `latexmk book-main_zh.tex -f`, the force flag being there because of missing characters. The LaTeX layer in the repository is more than a set of chapter files. There is a custom class file, `EngC.cls`, a `.latexmkrc` that carries the build configuration, `book-macros.sty` and `math-macros.sty` for the shared macros, `math-theorems.sty` with a Chinese counterpart `math-theorems_zh.sty`, a `book-references.bib` bibliography, and a `proofreading/` directory. ## Running the chapter code in a uv managed environment The code that accompanies the chapters is run with `uv`, the Python package manager, and the readme is explicit that the environment is restricted to the repository. You navigate to the repository and run `uv sync`, which creates that environment. Then you go to the chapter folder you are interested in and navigate to the code directory, for example `chapters/chapter3/code`, and run the file you want with `uv run ` and observe the outputs. The `pyproject.toml` in the repository root describes what that environment contains, and the dependency list is a good map of the book's subject matter. It requires Python 3.13 or later. The scientific stack is `jax>=0.6.2` and `optax>=0.2.5` on one side, `torchvision>=0.22.1` on the other, with `numpy`, `matplotlib` and `pillow` for the data and plotting work, `beautifulsoup4` and `requests` for fetching and parsing, `tqdm` for progress, `openai` for model calls, and `pyright` for type checking. The presence of both JAX and PyTorch is the interesting detail. It means the book is not tied to a single framework, which suits a book about representations rather than about one library, and it also means the environment installs both, along with their accelerator requirements. ## The website pipeline runs make4ht and takes tens of minutes The online version of the book is built by a separate pipeline, and the readme documents it in full because the site is a first class output rather than an afterthought. The prerequisites are a local TeX distribution with `make4ht`, included in TexLive, the `uv` package manager, and an installation of ImageMagick. The first step is the same `uv sync`, which creates the environment. The second is to build the book first so that `book-main.bbl` is up to date, because the bibliography is an input to the HTML build. Then the pipeline runs: ``` bash website/latex_to_html/build.sh book-main.tex ``` That runs `make4ht`, generates MathJax macros, injects them into each HTML file and post-processes the output into `website/html/`. The readme warns that it may take a while, around 10 to 30 minutes. Previewing is a plain static server: ``` python -m http.server -d website/html ``` and then you open `http://localhost:8000/index.html`. The MathJax step is what makes the HTML usable rather than merely generated. Converting LaTeX to HTML produces mathematics as images or as broken fragments unless the macros are rewritten for a browser-side renderer, and that injection step is the reason the build takes tens of minutes rather than seconds. ## The AI helper depends on a proxy that is not open sourced There is a note in the website section that is worth reading twice, because it is the only part of the project that is not open. The AI helper calls a variety of different models by making queries to a Cloudflare Worker proxy, and the stated reason is that the project does not want to expose API keys to everyone. The consequence is stated without hedging: the worker will unfortunately not be open-sourced, and the readme points readers who really need access to a person rather than to a repository. That is a defensible choice for secrets management and an unfortunate one for reproducibility. Everything else in the project, the book, the chapters, the figures and the experiment code, can be built and run locally from the repository, and only this one convenience feature depends on infrastructure the project controls and keeps closed. So a reader who wants the book and the code is entirely unaffected, and a reader who wants to run the same AI helper on their own account is dependent on the maintainers. It is also worth naming the pattern: this is a common shape for academic machine learning projects with an LLM-assisted tool, where the public artefact is the science and the hosted convenience is the part that cannot be forked. ## Contributing, and why the slides live on object storage The contribution instructions are detailed to the point of being a template, and they start with the practical steps: make a branch on GitHub with any name that is not taken, clone the repository, check the branch out locally, make the edits, then add, commit and push. ``` git clone https://github.com/Ma-Lab-Berkeley/deep-representation-learning-book.git ``` ``` git checkout -b my_new_branch ``` ``` git add git commit -m "" git push -u origin my_new_branch ``` The pull request goes to `main` through the GitHub UI, and the readme expects revision from a core contributor. Two requests are made explicitly: use English, because it maximises the number of people who can help, and follow the existing patterns, for code and for LaTeX alike. One design decision explains a lot about the repository's shape. The community page contains many slides and other PDFs, and those are hosted on Cloudflare R2 rather than committed to git. The stated reason is to limit the overall size of the repository so that it stays easy to clone and edit. For a book repository whose artefact is a PDF per chapter, that is a sensible trade, and it also means a fork carries the text and the code but not the slide archive. The issue template asks for system details, the operating system, the Python version, the `uv` version and the configuration of any GPUs or TPUs you are using, which is a fair signal of what the code needs to run. ## Where the book repository is the wrong tool The limits are about what kind of artefact this is. First, it is not a library and not a course. The code lives in `chapters/` next to the text that explains it, and each script is an experiment for one chapter. There is no package, no public API, no test suite for the code and no release stream; the repository publishes no GitHub releases. A team that wants a maintained, versioned, supported implementation of anything in the book should read the book and write their own code, which is exactly what the project intends. Second, the environment is demanding. Python 3.13 or later, JAX and optax, PyTorch and torchvision, and an accelerator configuration you are asked to specify when you report a problem. That is fine for a research environment and a poor fit for a quick tutorial on a laptop. Third, there are signs of an in-progress revision in the tree. There is a `book-main_ro.tex` alongside `book-main.tex`, a `book-main_zh.tex` for the translation, and a `bookv2_sync_aliases.sh` script whose name suggests it synchronises aliases for a second version of the book. A reader who wants to know which text is current should check which file the website build script consumes, and the readme does not spell out the relationship between them. Fourth, the citation information in the readme does not match the repository title. The BibTeX entry is for a book titled Principles and Practice of Deep Representation Learning, authored by Buchanan, Pai, Wang and Ma, with the key `ppdrl2026`, while the repository and the site are titled Learning Deep Representations of Data Distributions. A mismatch like that matters in a project whose whole point is citation, so anyone citing this work should check the current bibliography rather than copying the snippet. Finally, the licence field is not stated in the project metadata, and the readme has no licence section. For a repository of LaTeX sources and figure code that you are explicitly invited to fork, translate and contribute to, that is a gap worth raising with the maintainers rather than assuming. ## Conclusion deep-representation-learning-book fits a reader who wants the book as a PDF or the website, a lecturer who wants to rebuild or translate a chapter, and a researcher who wants the exact code behind a figure rather than a paraphrase of it. It does not fit someone looking for a maintained library or a runnable course with tests and pinned hardware, because the code is chapter-scoped experiment scripts rather than a package with a supported API. It is also the wrong tool if you need the AI helper without the team's proxy. Before you build, check that you have TexLive with latexmk and make4ht, expect the website pipeline to take ten to thirty minutes, and note that the AI helper depends on a Cloudflare Worker that the project states is not open sourced. ## FAQ ### How do I build the book from the repository? Install a local pdflatex distribution with TexLive and latexmk, then run `latexmk book-main.tex` in the repository base folder and read `book-main.pdf`. Individual chapters build the same way, for example `latexmk classic-models.tex` inside `chapters/chapter2`. ### How do I run the code that comes with a chapter? Use uv. Run `uv sync` in the repository to create a Python environment restricted to the repository, change into the chapter's code directory such as `chapters/chapter3/code`, and run the file with `uv run `. The environment requires Python 3.13 or later. ### How is the website version of the book built? Build the book first so that book-main.bbl is current, then run `bash website/latex_to_html/build.sh book-main.tex`, which runs make4ht, generates MathJax macros, injects them into each HTML file and writes to `website/html/`. The readme warns that this takes around 10 to 30 minutes. ### Why is part of the AI helper not open source? The readme explains that the AI helper calls several models through a Cloudflare Worker proxy so that API keys are not exposed, and that the worker will not be open-sourced as a result. Readers who need direct access are directed to a maintainer. ### Can I contribute a translation or fix a chapter? Yes. Fork the repository onto a branch, make your edits, commit and push, then open a pull request to main through the GitHub UI. The readme asks for English in issues and pull requests so that more people can help, and asks that you follow the existing code and LaTeX patterns. ## Sources - [Issues](https://github.com/Ma-Lab-Berkeley/deep-representation-learning-book/issues) - [Ma-Lab-Berkeley/deep-representation-learning-book on GitHub](https://github.com/Ma-Lab-Berkeley/deep-representation-learning-book) - [Project website](https://ma-lab-berkeley.github.io/deep-representation-learning-book/) - [README](https://github.com/Ma-Lab-Berkeley/deep-representation-learning-book/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ma-lab-berkeley-deep-representation-learning-book