Metadata-Version: 2.4
Name: swift-book-pdf
Version: 2.6.0
Summary: Generate polished PDF and EPUB editions of The Swift Programming Language book.
Keywords: swift,book,pdf,epub
Author: Evangelos Kassos
Author-email: Evangelos Kassos <github@evangeloskassos.com>
License-Expression: Apache-2.0
Requires-Dist: pillow>=12.1.1,<13.0.0
Requires-Dist: pygments>=2.20.0,<3.0.0
Requires-Dist: tqdm>=4.67.3,<5.0.0
Requires-Dist: pydantic>=2.12.5,<3.0.0
Requires-Dist: click>=8.3.1,<9.0.0
Requires-Dist: latexminted>=0.6.0,<0.7.0 ; python_full_version < '3.14'
Requires-Dist: latexminted>=0.7.1,<0.8.0 ; python_full_version >= '3.14'
Requires-Python: >=3.10
Project-URL: repository, https://github.com/ekassos/swift-book-pdf.git
Project-URL: issues, https://github.com/ekassos/swift-book-pdf/issues
Project-URL: changelog, https://github.com/ekassos/swift-book-pdf/blob/main/CHANGELOG.md
Project-URL: documentation, https://github.com/ekassos/swift-book-pdf/wiki
Project-URL: releasenotes, https://github.com/ekassos/swift-book-pdf/releases
Description-Content-Type: text/markdown

# 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/the-swift-programming-language/id6762236679">
    <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/the-swift-programming-language/id6762236679">Open in Apple Books &#8599;</a></p>
      <a href="https://books.apple.com/us/book/the-swift-programming-language/id6762236679"><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>

<p align="center">
  <a href="https://github.com/ekassos/swift-book-archive/releases/latest/download/swift_book.epub">Download EPUB &#8599;</a>&nbsp;&nbsp;·&nbsp;&nbsp;For versioned archives of the EPUB edition, see
  <a href="https://github.com/ekassos/swift-book-archive">swift-book-archive</a>.
</p>

### 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:-PDF#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:-PDF#rendering-modes--) in Letter [paper size](https://github.com/ekassos/swift-book-pdf/wiki/Customization-Options:-PDF#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).

## License and Acknowledgments

Copyright © 2025–2026 Evangelos Kassos. *swift-book-pdf* is distributed under the Apache License, Version 2.0.

When you don't [provide an input path](https://github.com/ekassos/swift-book-pdf/wiki/Customization-Options:-PDF#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.

Editions generated by *swift-book-pdf* are derived from the *swift-book* [source](https://github.com/swiftlang/swift-book) and are modified versions of the original work, converted and formatted for distribution. See the Acknowledgments chapter in each edition for more details. Passing `--dangerously-skip-legal-notices` suppresses the Acknowledgments chapter. Use of this option does not waive, limit, or satisfy any otherwise applicable legal obligations. Any person distributing an edition generated with this option remains solely responsible for compliance with all applicable attribution, licensing, trademark, notice, and non-affiliation requirements.

`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-docc-render* repository is part of the Swift.org open source project, which is licensed under the Apache License, Version 2.0 with Runtime Library Exception. See https://swift.org/LICENSE.txt for more details. Copyright © 2021–2025 Apple Inc. and the Swift project authors. The Swift project authors are credited at https://swift.org/CONTRIBUTORS.txt. See [THIRD-PARTY-NOTICES.txt](THIRD-PARTY-NOTICES.txt) for more details.

The Swift logo is a trademark of Apple Inc. Neither this project nor output generated by *swift-book-pdf* is published by, endorsed by, or affiliated with Apple Inc. or the Swift.org open source project.
