# PDF & EPUB Renderer for _The Swift Programming Language_

Convert the DocC source for _The Swift Programming Language_ book into polished PDF and EPUB editions.

<picture>
  <!-- User prefers light mode: -->
  <source srcset="https://github.com/user-attachments/assets/87ccccc0-0d41-4768-be03-bb91a083207d" media="(prefers-color-scheme: light)"/>

  <!-- User prefers dark mode: -->
  <source srcset="https://github.com/user-attachments/assets/c648898e-c27c-4819-a418-7ea2e08c83ba" media="(prefers-color-scheme: dark)" alt="The image shows The Swift Programming Language book displayed across three devices: a 14-inch MacBook Pro (M4) in Silver, an 11-inch iPad Pro (M4) in Space Gray, and an iPhone 17 Pro in Deep Blue. Each screen shows pages from the book titled Collection Types, featuring diagrams, code snippets, and explanations about arrays, sets, and dictionaries in Swift. Below the devices, centered text reads 'Swift Book PDF' followed by a large bold headline, 'Learn Swift anywhere.' The background is black, emphasizing the devices and text."/>

  <!-- User has no color preference: -->
  <img width="100%" alt="The image shows The Swift Programming Language book displayed across three devices: a 14-inch MacBook Pro (M4) in Silver, an 11-inch iPad Pro (M4) in Space Gray, and an iPhone 17 Pro in Deep Blue. Each screen shows pages from the book titled Collection Types, featuring diagrams, code snippets, and explanations about arrays, sets, and dictionaries in Swift. Below the devices, centered text reads 'Swift Book PDF' followed by a large bold headline, 'Learn Swift anywhere.' The background is clean and light gray, emphasizing the devices and text." src="https://github.com/user-attachments/assets/87ccccc0-0d41-4768-be03-bb91a083207d" />
</picture>

<p align="center"> Jump to:
  <a href="#features"><strong>Features</strong></a> ·
  <a href="#installation"><strong>Installation</strong></a> ·
  <a href="#usage"><strong>Usage</strong></a> ·
  <a href="#customization"><strong>Customization</strong></a> ·
  <a href="https://github.com/ekassos/swift-book-pdf/wiki"><strong>Wiki</strong></a>
</p>

## Get the book

### EPUB edition
<table>
  <tr>
    <td valign="middle" width="70%">
  <a href="https://books.apple.com/us/book-series/swift-programming-series/id1887443754">
    <picture>
  <!-- User prefers light mode: -->
  <source srcset="https://github.com/user-attachments/assets/7682de0f-35ae-4391-8a01-2b802475725e" media="(prefers-color-scheme: light)"/>

  <!-- User prefers dark mode: -->
  <source srcset="https://github.com/user-attachments/assets/dc82db2f-2816-4246-9492-04559032ecca" media="(prefers-color-scheme: dark)"/>

  <!-- User has no color preference: -->
  <img alt="Read the latest edition. Click this image to get it on Apple Books." src="https://github.com/user-attachments/assets/7682de0f-35ae-4391-8a01-2b802475725e"/>
</picture>
</a>
    </td>
    <td valign="middle" width="30%">
      <p><i>The Swift Programming Language</i>, optimized for Apple Books.</p>
      <p><a href="https://books.apple.com/us/book-series/swift-programming-series/id1887443754">Open in Apple Books &#8599;</a></p>
      <a href="https://books.apple.com/us/book-series/swift-programming-series/id1887443754"><img src="https://toolbox.marketingtools.apple.com/api/v2/badges/get-it-on-apple-books/badge/en-us" alt="Get it on Apple Books"/></a>
    </td>
  </tr>
</table>

### PDF editions
<table>
  <tr>
    <td valign="middle" align="center" width="50%">
      <a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_digital.pdf">
    <picture>
  <!-- User prefers light mode: -->
  <source srcset="https://github.com/user-attachments/assets/f9383740-d4d3-4edf-afda-4c293e26a509" media="(prefers-color-scheme: light)"/>

  <!-- User prefers dark mode: -->
  <source srcset="https://github.com/user-attachments/assets/41564d42-b09f-4250-983a-20c8edcf68d6" media="(prefers-color-scheme: dark)"/>

  <!-- User has no color preference: -->
  <img src="https://github.com/user-attachments/assets/f9383740-d4d3-4edf-afda-4c293e26a509"/>
</picture>
</a>
      <p><a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_digital.pdf"><img height="35px" alt="Download Digital edition PDF" src="https://github.com/user-attachments/assets/3fb49e16-17c8-4696-85e5-486c2b759048" /></a></p>
    </td>
    <td valign="middle" align="center" width="50%">
      <a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_print.pdf">
    <picture>
  <!-- User prefers light mode: -->
  <source srcset="https://github.com/user-attachments/assets/01157903-a30b-41a9-9d7d-7f4d0167d392" media="(prefers-color-scheme: light)"/>

  <!-- User prefers dark mode: -->
  <source srcset="https://github.com/user-attachments/assets/3d4c78a8-4d9b-4420-a82d-9b066be84f5f" media="(prefers-color-scheme: dark)"/>

  <!-- User has no color preference: -->
  <img src="https://github.com/user-attachments/assets/01157903-a30b-41a9-9d7d-7f4d0167d392"/>
</picture>
</a>
      <p><a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_print.pdf"><img height="35px" alt="Download Print edition PDF" src="https://github.com/user-attachments/assets/3fb49e16-17c8-4696-85e5-486c2b759048" /></a></p>
    </td>
    </tr>
      <tr>
    <td valign="middle" align="center" width="50%">
       <a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_digital_dark.pdf">
    <picture>
  <!-- User prefers light mode: -->
  <source srcset="https://github.com/user-attachments/assets/4bd5252d-fa8b-45d6-9d22-ab18146821c4" media="(prefers-color-scheme: light)"/>

  <!-- User prefers dark mode: -->
  <source srcset="https://github.com/user-attachments/assets/42e0452c-ae9d-4d49-9e4f-bc2098145b91" media="(prefers-color-scheme: dark)"/>

  <!-- User has no color preference: -->
  <img src="https://github.com/user-attachments/assets/4bd5252d-fa8b-45d6-9d22-ab18146821c4"/>
</picture>
</a>
      <p><a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_digital_dark.pdf"><img height="35px" alt="Download Digital Dark edition PDF" src="https://github.com/user-attachments/assets/3fb49e16-17c8-4696-85e5-486c2b759048" /></a></p>
    </td>
            <td valign="middle" align="center" width="50%">
      <a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_print_dark.pdf">
    <picture>
  <!-- User prefers light mode: -->
  <source srcset="https://github.com/user-attachments/assets/3baa6961-ad5d-4848-b333-2858b6a29347" media="(prefers-color-scheme: light)"/>

  <!-- User prefers dark mode: -->
  <source srcset="https://github.com/user-attachments/assets/c2f0997c-d2dd-4a63-93ef-4705136fb5c2" media="(prefers-color-scheme: dark)"/>

  <!-- User has no color preference: -->
  <img src="https://github.com/user-attachments/assets/3baa6961-ad5d-4848-b333-2858b6a29347"/>
</picture>
</a>
      <p><a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book_print_dark.pdf"><img height="35px" alt="Download Print Dark edition PDF" src="https://github.com/user-attachments/assets/3fb49e16-17c8-4696-85e5-486c2b759048" /></a></p>
    </td>
    </tr>
</table>

<p align="center">
  For versioned archives of the PDF editions, see
  <a href="https://github.com/ekassos/swift-book-archive">swift-book-archive</a>.
</p>

## Features

### PDF Generation (`swift-book-pdf`)
- Generate a PDF edition of _The Swift Programming Language_, optimized for offline reading or printing.
- Choose from one of two [rendering modes](https://github.com/ekassos/swift-book-pdf/wiki/Customization-Options#rendering-modes--):
   - Digital mode with hyperlinks for cross-references between chapters and external links.
   - Print mode with page numbers accompanying cross-references between chapters and full URLs shown in footnotes for external links.
- Both versions follow the DocC rendering style used in [docs.swift.org](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/), including code highlighting.

### EPUB Generation (`swift-book-epub`)
- Generate an EPUB edition of _The Swift Programming Language_, ideal for e-readers and mobile devices.
- The generated EPUB file follows the rendering style used by TSPL editions up to Swift 5.7 [published on Apple Books](https://books.apple.com/us/book/the-swift-programming-language-swift-5-7/id881256329) and retains all internal references and external links.

## Requirements
- Python 3.10+
- Git
- Specifically for generating PDF editions with `swift-book-pdf`:
    - LuaTeX. If you don't have an existing LaTeX installation, see [MacTeX](https://www.tug.org/mactex/), [TeX Live](https://www.tug.org/texlive/), or [MiKTeX](https://miktex.org).
    - Fonts for typesetting. Learn [which fonts are required to typeset the TSPL book](https://github.com/ekassos/swift-book-pdf/wiki/Fonts).

## Installation
### Latest PyPI stable release
```
pip install swift-book-pdf
```

## Usage
### PDF generation
Call `swift-book-pdf` without any arguments to save the resulting PDF as `swift_book.pdf` in the current directory. The package defaults to the digital [rendering mode](https://github.com/ekassos/swift-book-pdf/wiki/Customization-Options#rendering-modes--) in Letter [paper size](https://github.com/ekassos/swift-book-pdf/wiki/Customization-Options#paper-sizes--).
```
$ swift-book-pdf

[INFO]: Downloading TSPL files...
[INFO]: Creating PDF in digital (light) mode...
[INFO]: PDF saved to ./swift-book.pdf
```

When invoked, `swift-book-pdf` will:
1. Clone the `swift-book` [repository](https://github.com/swiftlang/swift-book)
2. Convert all Markdown source files into a single LaTeX document
3. Render the LaTeX document into the final PDF document

### EPUB generation
Call `swift-book-epub` without any arguments to save the resulting EPUB as `swift_book.epub` in the current directory.
```
$ swift-book-epub
[INFO]: Downloading TSPL files...
[INFO]: Creating EPUB...
[INFO]: EPUB saved to ./swift_book.epub
```

## Customization
`swift-book-pdf` and `swift-book-epub` offer a range of options to customize your rendering of _The Swift Programming Language_ book. Learn how to [make the TSPL book your own](https://github.com/ekassos/swift-book-pdf/wiki/Customization-Options).

## Acknowledgments

When you don't [provide an input path](https://github.com/ekassos/swift-book-pdf/wiki/Customization-Options#input-path--), swift-book-pdf temporarily clones the swift-book [repository](https://github.com/swiftlang/swift-book) for processing at runtime, but no part of the repository is directly redistributed here.

`chapter-icon.png` and `chapter-icon~dark.png` are derived from the [`ArticleIcon.vue`](https://github.com/swiftlang/swift-docc-render/blob/1fe0a7a032b11272d0407317995169f79bba0d84/src/components/Icons/ArticleIcon.vue) component in the swift-docc-render [repository](https://github.com/swiftlang/swift-docc-render/).

The swift-book and swift-docc-render repositories are part of the Swift.org open source project, which is licensed under the Apache License v2.0 with Runtime Library Exception. See https://swift.org/LICENSE.txt for more details. The Swift project authors are credited at https://swift.org/CONTRIBUTORS.txt.

The Swift logo is a trademark of Apple Inc.
