From 23475e7b382250b9fa8571b91baa9d13cdf20bd7 Mon Sep 17 00:00:00 2001
From: Jirka Borovec <6035284+Borda@users.noreply.github.com>
Date: Mon, 18 Sep 2023 17:10:59 +0200
Subject: [PATCH] ci: unify docs makes flows (#162)

---
 .github/workflows/check-docs.yml | 71 ++++++++++++++++----------------
 CHANGELOG.md                     |  4 ++
 2 files changed, 39 insertions(+), 36 deletions(-)

diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml
index 69665520..d9ce3f17 100644
--- a/.github/workflows/check-docs.yml
+++ b/.github/workflows/check-docs.yml
@@ -1,4 +1,4 @@
-name: Check docs flow
+name: Building docs
 
 on:
   workflow_call:
@@ -13,11 +13,6 @@ on:
         default: './docs'
         required: false
         type: string
-      doctest:
-        description: 'test examples inside docs'
-        default: true
-        required: false
-        type: boolean
       timeout-minutes:
         description: 'timeout-minutes for each job'
         default: 15
@@ -36,6 +31,17 @@ on:
           {
             "SPHINX_MOCK_REQUIREMENTS": 0,
           }
+      make-target:
+        description: 'what test configs to run in json format'
+        required: false
+        type: string
+        default: |
+          ["html", "doctest", "linkcheck"]
+      install-tex:
+        description: 'optional installing Texlive support'
+        required: false
+        type: boolean
+        default: false
 
 defaults:
   run:
@@ -46,10 +52,13 @@ env:
 
 jobs:
 
-  docs-test:
+  make-docs:
     runs-on: ubuntu-20.04
     env: ${{ fromJSON(inputs.env-vars) }}
-    if: inputs.doctests != 'false'
+    strategy:
+      fail-fast: false
+      matrix:
+        check: ${{ fromJSON(inputs.make-target) }}
     steps:
     - name: Checkout 🛎
       uses: actions/checkout@v4
@@ -61,55 +70,45 @@ jobs:
       with:
         python-version: ${{ inputs.python-version }}
 
+    - name: Install pandoc & texlive
+      if: inputs.install-tex == 'true'
+      run: |
+        sudo apt-get update --fix-missing
+        sudo apt-get install -y pandoc texlive-latex-extra dvipng texlive-pictures
+    # todo: consider adding cache with separate restore/dave
     - name: Install dependencies
       run: |
-        pip install -e . -U -r ${{ inputs.requirements-file }} -f ${TORCH_URL}
         pip --version
+        pip install -e . -U -r ${{ inputs.requirements-file }} -f ${TORCH_URL}
         pip list
-      shell: bash
 
     # TODO: re-enable after the external usage is resolved, see #51
     # - uses: ./.github/actions/pip-list
 
     - name: Test Documentation
+      if: ${{ matrix.check == 'doctest' }}
       working-directory: ${{ inputs.docs-dir }}
-      env:
-        SPHINX_MOCK_REQUIREMENTS: 0
       run: |
         make doctest
         make coverage
 
-
-  docs-html:
-    runs-on: ubuntu-20.04
-    env: ${{ fromJSON(inputs.env-vars) }}
-    steps:
-    - name: Checkout 🛎
-      uses: actions/checkout@v4
-      with:
-        submodules: recursive
-
-    - name: Set up Python 🐍 ${{ inputs.python-version }}
-      uses: actions/setup-python@v4
-      with:
-        python-version: ${{ inputs.python-version }}
-
-    - name: Install dependencies
-      run: |
-        pip install -e . -U -r ${{ inputs.requirements-file }} -f ${TORCH_URL}
-        sudo apt-get update --fix-missing
-        sudo apt-get install -y texlive-latex-extra dvipng texlive-pictures
-        python --version
-        pip --version
-        pip list
+    - name: Check External Links
+      if: ${{ matrix.check == 'linkcheck' }}
+      working-directory: ${{ inputs.docs-dir }}
+      run: make  linkcheck SPHINXOPTS="--keep-going"
 
     - name: Build documentation
+      if: ${{ matrix.check == 'html' }}
       working-directory: ${{ inputs.docs-dir }}
       run: make html --debug SPHINXOPTS="-W --keep-going"
 
+    - name: Keep artifact
+      id: keep-artifact
+      run: python -c "print('DAYS=' + str(7 if '${{ github.event_name }}'.startswith('pull_request') else 0))" >> $GITHUB_OUTPUT
     - name: Upload built docs
+      if: ${{ matrix.check == 'html' }}
       uses: actions/upload-artifact@v3
       with:
         name: docs-${{ github.sha }}
         path: ${{ inputs.docs-dir }}/build/html/
-      if: success()
+        retention-days: ${{ steps.keep-artifact.outputs.DAYS }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 38b5af2c..78509b3c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Updated/Extended the `requires` wrapper ([#146](https://github.com/Lightning-AI/utilities/pull/146))
 
+
+- CI: unified/extended docs makes flows ([#162](https://github.com/Lightning-AI/utilities/pull/162))
+
+
 ### Fixed
 
 - Fixed issue with `is_overridden` falsely returning True when the parent method is wrapped ([#149](https://github.com/Lightning-AI/utilities/pull/149))