Przeglądaj źródła

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 lat temu
rodzic
commit
74ac839609
4 zmienionych plików z 45 dodań i 22 usunięć
  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:
 on:
   push:
   push:
   pull_request:
   pull_request:
-  schedule:
-    # Every week on Monday at midnight (UTC).
-    # This keeps the generated HTML documentation fresh.
-    - cron: '0 0 * * 1'
 
 
 jobs:
 jobs:
   build:
   build:
@@ -23,25 +19,11 @@ jobs:
           sudo pip3 install codespell
           sudo pip3 install codespell
 
 
       - name: Linter checks
       - name: Linter checks
-        if: github.event_name != 'schedule'
         run: |
         run: |
           bash _tools/format.sh
           bash _tools/format.sh
           codespell -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt {about,community,development,getting_started,tutorials}/**/*.rst
           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
       - name: Sphinx build
         run: |
         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).
 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
 ## Theming
 
 
 The Godot documentation uses the default ``sphinx_rtd_theme`` with many
 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)
 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)
 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)
 5. [Translating the documentation](https://docs.godotengine.org/en/latest/community/contributing/editor_and_docs_localization.html)
-    
+
 ## License
 ## 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".
 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 three dots in the top-left corner, choose **Offline data**.
 - Click the **Install** link next to the Godot documentation.
 - 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
 .. note:: Godot Engine is an open source project developed by a community of
           volunteers. The documentation team can always use your
           volunteers. The documentation team can always use your
           feedback and help to improve the tutorials and class reference. If
           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
           <https://hosted.weblate.org/engage/godot-engine/>`_ into your
           language, or talk to us on either the ``#documentation``
           language, or talk to us on either the ``#documentation``
           channel on `Discord <https://discord.gg/zH7NUgz>`_, or the
           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/>`_!
           <https://chat.godotengine.org/>`_!
 
 
 .. centered:: |weblate_widget|
 .. centered:: |weblate_widget|