Build ePubs of the documentation for offline reading

Sightwalker · May 4, 2023 · 9d1dd80 · 9d1dd80
1 parent 4cc818f
commit 9d1dd80
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 4 deletions.
diff --git a/.github/workflows/build_offline_docs.yml b/.github/workflows/build_offline_docs.yml
@@ -8,12 +8,12 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
         branch:
           - master
-          - stable
+          - 3.6
     steps:
       - uses: actions/checkout@v3
         with:
@@ -23,8 +23,10 @@ jobs:
         run: |
           sudo pip3 install -r requirements.txt
           sudo pip3 install codespell
+          sudo apt update
+          sudo apt install parallel libwebp7
 
-      - name: Sphinx build HTML
+      - name: Sphinx - Build HTML
         run: make SPHINXOPTS='--color' html
 
       - uses: actions/upload-artifact@v3
@@ -34,3 +36,25 @@ jobs:
           # Keep the current build and the previous build (in case a scheduled build failed).
           # This makes it more likely to have at least one successful build available at all times.
           retention-days: 15
+
+      - name: Sphinx - Build ePub
+        run: |
+          # Convert WebP images to PNG and replace references, so that ePub readers can display those images.
+          # The ePub 3.0 specification has WebP support, but it's not widely supported by apps and e-readers yet.
+          shopt -s globstar nullglob
+          parallel --will-cite convert {} {.}.png ::: {about,community,contributing,getting_started,img,tutorials}/**/*.webp
+          parallel --will-cite sed -i "s/\\.webp$/\\.png/g" ::: {about,community,contributing,getting_started,tutorials}/**/*.rst
+
+          # Remove banners at the top of each page when building `latest`.
+          sed -i 's/"godot_is_latest": True/"godot_is_latest": False/' conf.py
+          sed -i 's/"godot_show_article_status": True/"godot_show_article_status": False/' conf.py
+
+          make SPHINXOPTS='--color' epub
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: godot-docs-epub-${{ matrix.branch }}
+          path: _build/epub/GodotEngine.epub
+          # Keep the current build and the previous build (in case a scheduled build failed).
+          # This makes it more likely to have at least one successful build available at all times.
+          retention-days: 15
diff --git a/README.md b/README.md
@@ -6,10 +6,26 @@ They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) docum
 
 ## Download for offline use
 
-You can [download an HTML copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip)
+To browse the documentation offline, you can use the mirror of the documentation
+hosted on [DevDocs](https://devdocs.io/godot/). To enable offline browsing on
+DevDocs, you need to:
+
+- Click the three dots in the top-left corner, choose **Preferences**.
+- Enable the desired version of the Godot documentation by checking the box
+  next to it in the sidebar.
+- Click the three dots in the top-left corner, choose **Offline data**.
+- Click the **Install** link next to the Godot documentation.
+
+You can also
+[download an HTML copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip)
 for offline reading (updated every Monday). Extract the ZIP archive then open
 the top-level `index.html` in a web browser.
 
+For mobile devices or e-readers, you can also
+[download an ePub copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-master.zip)
+for offline reading (updated every Monday). Extract the ZIP archive then open
+the `GodotEngine.epub` file in an e-book reader application.
+
 ## Theming
 
 The Godot documentation uses the default `sphinx_rtd_theme` with many

diff --git a/index.rst b/index.rst
@@ -65,6 +65,9 @@ You can also `download an HTML copy <https://nightly.link/godotengine/godot-docs
 for offline reading (updated every Monday). Extract the ZIP archive then open
 the top-level ``index.html`` in a web browser.
 
+For mobile devices or e-readers, you can also `download an ePub copy <https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-master.zip>`__
+for offline reading (updated every Monday). Extract the ZIP archive then open
+the ``GodotEngine.epub`` file in an e-book reader application.
 
 .. Below is the main table-of-content tree of the documentation website.
    It is hidden on the page itself, but it makes up the sidebar for navigation.