diff --git a/.github/workflows/build_offline_docs.yml b/.github/workflows/build_offline_docs.yml index 4c3d0837bed..1800e1289a0 100644 --- 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 index 74a2826c3a9..86fde73a35c 100644 --- 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 index c4ee7af14f7..d861e51d973 100644 --- a/index.rst +++ b/index.rst @@ -65,6 +65,9 @@ You can also `download an HTML copy `__ +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.