Browse Source

Use a separate GitHub Actions workflow to build offline documentation (#4733)

This is required to get a permalink using https://nightly.link
as we need the workflow containing the offline docs ZIP artifact
to always be the latest one. Creating a second workflow is a good
way to solve this.

This also makes it easier to distinguish between linting checks
and offline documentation builds in the repository's Actions tab.
Hugo Locurcio 4 years ago
parent
commit
74ac839609
4 changed files with 45 additions and 22 deletions
  1. 31 0
      .github/workflows/build_offline_docs.yml
  2. 2 20
      .github/workflows/ci.yml
  3. 7 1
      README.md
  4. 5 1
      index.rst

+ 31 - 0
.github/workflows/build_offline_docs.yml

@@ -0,0 +1,31 @@
+name: Build documentation for offline usage
+on:
+  schedule:
+    # Every week on Monday at midnight (UTC).
+    # This keeps the generated HTML documentation fresh.
+    - cron: '0 0 * * 1'
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install dependencies
+        run: |
+          sudo pip3 install -r requirements.txt
+          sudo pip3 install codespell
+
+      # Build the HTML to upload it.
+      - name: Sphinx build
+        run: |
+          sphinx-build --color -d _build/doctrees -W . _build/html
+
+      - uses: actions/upload-artifact@v2
+        with:
+          name: godot-docs-html
+          path: _build/html
+          # 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

+ 2 - 20
.github/workflows/ci.yml

@@ -2,10 +2,6 @@ name: Continuous integration
 on:
   push:
   pull_request:
-  schedule:
-    # Every week on Monday at midnight (UTC).
-    # This keeps the generated HTML documentation fresh.
-    - cron: '0 0 * * 1'
 
 jobs:
   build:
@@ -23,25 +19,11 @@ jobs:
           sudo pip3 install codespell
 
       - name: Linter checks
-        if: github.event_name != 'schedule'
         run: |
           bash _tools/format.sh
           codespell -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt {about,community,development,getting_started,tutorials}/**/*.rst
 
+      # Use dummy builder to improve performance as we don't need the generated HTML in this workflow.
       - name: Sphinx build
         run: |
-          if [[ "$GITHUB_EVENT_NAME" == "schedule" ]]; then
-            # Build HTML to upload it.
-            sphinx-build --color -d _build/doctrees -W . _build/html
-          else
-            # Use dummy builder to improve performance.
-            sphinx-build --color -b dummy -d _build/doctrees -W . _build/html
-          fi
-
-      - uses: actions/upload-artifact@v2
-        if: github.event_name == 'schedule'
-        with:
-          name: godot-docs-html
-          path: _build/html
-          # Keep the current build and the previous build (in case a scheduled build failed).
-          retention-days: 15
+          sphinx-build --color -b dummy -d _build/doctrees -W . _build/html

+ 7 - 1
README.md

@@ -4,6 +4,12 @@ This repository contains the source files of [Godot Engine](https://godotengine.
 
 They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) documentation builder to build the HTML documentation on [Godot's website](https://docs.godotengine.org).
 
+## Download for offline use
+
+You can [download an HTML copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html.zip)
+for offline reading (updated every Monday). Extract the ZIP archive then open
+the top-level `index.html` in a web browser.
+
 ## Theming
 
 The Godot documentation uses the default ``sphinx_rtd_theme`` with many
@@ -28,7 +34,7 @@ Here are some quick links to the areas you might be interested in:
 3. [Content guidelines](https://docs.godotengine.org/en/latest/community/contributing/content_guidelines.html)
 4. [Writing guidelines](https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html)
 5. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html)
-    
+
 ## License
 
 At the exception of the `classes/` folder, all the content of this repository is licensed under the Creative Commons Attribution 3.0 Unported license ([CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community".

+ 5 - 1
index.rst

@@ -42,6 +42,10 @@ DevDocs, you need to:
 - 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.zip>`__
+for offline reading (updated every Monday). Extract the ZIP archive then open
+the top-level ``index.html`` in a web browser.
+
 .. note:: Godot Engine is an open source project developed by a community of
           volunteers. The documentation team can always use your
           feedback and help to improve the tutorials and class reference. If
@@ -55,7 +59,7 @@ DevDocs, you need to:
           <https://hosted.weblate.org/engage/godot-engine/>`_ into your
           language, or talk to us on either the ``#documentation``
           channel on `Discord <https://discord.gg/zH7NUgz>`_, or the
-          ``#documentation`` channel on the `Godot Contributors Chat 
+          ``#documentation`` channel on the `Godot Contributors Chat
           <https://chat.godotengine.org/>`_!
 
 .. centered:: |weblate_widget|