Make use of GITHUB_OUTPUT and use it. Reduce specific steps with programmatic ones.

Signed-off-by: Pedro Algarvio <palgarvio@vmware.com>

.github/workflows/build-docs.yml

@@ -77,78 +77,22 @@ jobs:
           sudo cp -rfv .builddocs/builddocs/files/fonts/opentype/*.otf /usr/share/fonts/opentype/
           sudo fc-cache -f -v
 
-      - name: Build Documentation (HTML)
+      - name: Build Documentation (${{ matrix.docs-output }})
-        if: ${{ matrix.docs-output == 'html' }}
+        id: build-docs
         shell: bash
+        continue-on-error: ${{ matrix.docs-output == 'linkcheck' || matrix.docs-output == 'spellcheck' }}
         env:
           LATEST_RELEASE: "${{ inputs.salt-version }}"
           SALT_ON_SALTSTACK: "1"
+          ARCHIVE_FILENAME: "${{ format('salt-{0}-docs-{1}.tar.xz', inputs.salt-version, matrix.docs-output) }}"
         run: |
-          tools docs html --archive salt-${{ inputs.salt-version }}-docs-html.tar.xz
+          tools docs ${{ matrix.docs-output }}
 
-      - name: Upload Built Documentation Archive (HTML)
+      - name: Upload Built Documentation Artifact(${{ matrix.docs-output }})
-        if: ${{ matrix.docs-output == 'html' }}
+        if: ${{ steps.build-docs.outputs.has-artifacts == 'true' }}
         uses: actions/upload-artifact@v3
         with:
-          name: salt-${{ inputs.salt-version }}-docs-html.tar.xz
+          name: ${{ steps.build-docs.outputs.artifact-name }}
-          path: salt-${{ inputs.salt-version }}-docs-html.tar.xz
+          path: ${{ steps.build-docs.outputs.artifact-path }}
           retention-days: 7
           if-no-files-found: error
-
-      - name: Build Documentation (ePUB)
-        if: ${{ matrix.docs-output == 'epub' }}
-        shell: bash
-        env:
-          LATEST_RELEASE: "${{ inputs.salt-version }}"
-          SALT_ON_SALTSTACK: "1"
-        run: |
-          tools docs epub
-          mv doc/_build/epub/Salt.epub doc/_build/epub/salt-${{ inputs.salt-version }}.epub
-
-      - name: Upload Built Documentation Archive (ePub)
-        if: ${{ matrix.docs-output == 'epub' }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: salt-${{ inputs.salt-version }}.epub
-          path: doc/_build/epub/salt-${{ inputs.salt-version }}.epub
-          retention-days: 7
-          if-no-files-found: error
-
-      - name: Build Documentation (PDF)
-        if: ${{ matrix.docs-output == 'pdf' }}
-        shell: bash
-        env:
-          LATEST_RELEASE: "${{ inputs.salt-version }}"
-          SALT_ON_SALTSTACK: "1"
-        run: |
-          tools docs pdf
-          mv doc/_build/latex/Salt.pdf doc/_build/latex/salt-${{ inputs.salt-version }}.pdf
-
-      - name: Upload Built Documentation Archive (PDF)
-        if: ${{ matrix.docs-output == 'pdf' }}
-        uses: actions/upload-artifact@v3
-        with:
-          name: salt-${{ inputs.salt-version }}.pdf
-          path: doc/_build/latex/Salt-${{ inputs.salt-version }}.pdf
-          retention-days: 7
-          if-no-files-found: error
-
-      - name: Check Documentation Links
-        if: ${{ matrix.docs-output == 'linkcheck' }}
-        shell: bash
-        continue-on-error: true
-        env:
-          LATEST_RELEASE: "${{ inputs.salt-version }}"
-          SALT_ON_SALTSTACK: "1"
-        run: |
-          tools docs linkcheck
-
-      - name: Check Documentation Spelling
-        if: ${{ matrix.docs-output == 'spellcheck' }}
-        shell: bash
-        continue-on-error: true
-        env:
-          LATEST_RELEASE: "${{ inputs.salt-version }}"
-          SALT_ON_SALTSTACK: "1"
-        run: |
-          tools docs spellcheck

tools/docs.py

@@ -62,14 +62,39 @@ def man(ctx: Context, no_clean: bool = False):
         },
     },
 )
-def html(ctx: Context, no_clean: bool = False, archive: pathlib.Path = None):
+def html(
+    ctx: Context,
+    no_clean: bool = False,
+    archive: pathlib.Path = os.environ.get("ARCHIVE_FILENAME"),  # type: ignore[assignment]
+):
     if no_clean is False:
         ctx.run("make", "clean", cwd="doc/", check=True)
     ctx.run("make", "html", "SPHINXOPTS=-W --keep-going", cwd="doc/", check=True)
+    github_output = os.environ.get("GITHUB_OUTPUT")
     if archive is not None:
         ctx.info(f"Compressing the generated documentation to '{archive}'...")
         ctx.run("tar", "caf", str(archive.resolve()), ".", cwd="doc/_build/html")
 
+        if github_output is not None:
+            with open(github_output, "a", encoding="utf-8") as wfh:
+                wfh.write(
+                    "has-artifacts=true\n"
+                    f"artifact-name={archive.resolve().name}\n"
+                    f"artifact-path={archive.resolve()}\n"
+                )
+    elif github_output is not None:
+        artifact = tools.utils.REPO_ROOT / "doc" / "_build" / "html"
+        if "LATEST_RELEASE" in os.environ:
+            artifact_name = f"salt-{os.environ['LATEST_RELEASE']}-docs-html"
+        else:
+            artifact_name = "salt-docs-html"
+        with open(github_output, "a", encoding="utf-8") as wfh:
+            wfh.write(
+                "has-artifacts=true\n"
+                f"artifact-name={artifact_name}\n"
+                f"artifact-path={artifact.resolve()}\n"
+            )
+
 
 @docs.command(
     name="epub",
@@ -84,6 +109,21 @@ def epub(ctx: Context, no_clean: bool = False):
         ctx.run("make", "clean", cwd="doc/", check=True)
     ctx.run("make", "epub", cwd="doc/", check=True)
 
+    artifact = tools.utils.REPO_ROOT / "doc" / "_build" / "epub" / "Salt.epub"
+    if "LATEST_RELEASE" in os.environ:
+        shutil.move(
+            artifact, artifact.parent / f"Salt-{os.environ['LATEST_RELEASE']}.epub"
+        )
+        artifact = artifact.parent / f"Salt-{os.environ['LATEST_RELEASE']}.epub"
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output is not None:
+        with open(github_output, "a", encoding="utf-8") as wfh:
+            wfh.write(
+                "has-artifacts=true\n"
+                f"artifact-name={artifact.resolve().name}\n"
+                f"artifact-path={artifact.resolve()}\n"
+            )
+
 
 @docs.command(
     name="pdf",
@@ -101,6 +141,21 @@ def pdf(ctx: Context, no_clean: bool = False):
         ctx.run("make", "clean", cwd="doc/", check=True)
     ctx.run("make", "pdf", "SPHINXOPTS=-W", cwd="doc/", check=True)
 
+    artifact = tools.utils.REPO_ROOT / "doc" / "_build" / "latex" / "Salt.pdf"
+    if "LATEST_RELEASE" in os.environ:
+        shutil.move(
+            artifact, artifact.parent / f"Salt-{os.environ['LATEST_RELEASE']}.pdf"
+        )
+        artifact = artifact.parent / f"Salt-{os.environ['LATEST_RELEASE']}.pdf"
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output is not None:
+        with open(github_output, "a", encoding="utf-8") as wfh:
+            wfh.write(
+                "has-artifacts=true\n"
+                f"artifact-name={artifact.resolve().name}\n"
+                f"artifact-path={artifact.resolve()}\n"
+            )
+
 
 @docs.command(
     name="linkcheck",
@@ -120,6 +175,10 @@ def linkcheck(ctx: Context, no_clean: bool = False):
         cwd="doc/",
         check=True,
     )
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output is not None:
+        with open(github_output, "a", encoding="utf-8") as wfh:
+            wfh.write("has-artifacts=false\n")
 
 
 @docs.command(
@@ -140,3 +199,7 @@ def spellcheck(ctx: Context, no_clean: bool = False):
         cwd="doc/",
         check=True,
     )
+    github_output = os.environ.get("GITHUB_OUTPUT")
+    if github_output is not None:
+        with open(github_output, "a", encoding="utf-8") as wfh:
+            wfh.write("has-artifacts=false\n")