diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index f8de458f811..6d51c2a1326 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -3,8 +3,49 @@ name: "Documentation Build" on: workflow_call: - # inputs: - + inputs: + builder: + description: | + The builder to use for the documentation. Default is "html". + required: false + default: "html" + type: string + + build_pdf: + description: | + Whether to build the PDF documentation. Default is "false". + required: false + default: true + type: boolean + + build_cheatsheet: + description: | + Whether to build the cheatsheet. Default is "false". + required: false + default: true + type: boolean + + use_cache_examples: + description: | + Whether to use the examples cache. Default is "true". + required: false + default: true + type: boolean + + use_cache_doc_build: + description: | + Whether to use the doc build cache. Default is "true". + required: false + default: true + type: boolean + + use_cache_autosummary: + description: | + Whether to use the autosummary cache. Default is "true". + required: false + default: true + type: boolean + # Secrets secrets: license-server: @@ -29,7 +70,7 @@ jobs: ON_CI: True ON_DOCUMENTATION: TRUE PYANSYS_OFF_SCREEN: True - BUILD_CHEATSHEET: True + BUILD_CHEATSHEET: '${{ inputs.build_cheatsheet }}' MAPDL_IMAGE_VERSION_DOCS_BUILD: v24.2-ubuntu-student MAPDL_PACKAGE: ghcr.io/ansys/mapdl PYMAPDL_START_INSTANCE: FALSE @@ -39,6 +80,7 @@ jobs: DPF_START_SERVER: False GRPC_ENABLE_FORK_SUPPORT: false # See #3434 MAIN_PYTHON_VERSION: "3.12" + NOT_ON_RELEASE: ${{ github.ref == 'refs/heads/main' && !contains(github.ref, 'refs/tags') }} steps: - name: "Install Git and checkout project" @@ -83,7 +125,7 @@ jobs: - 'pyproject.toml' documentation: - 'examples/**' - - 'doc/**' + - 'doc/source/**' - 'pyproject.toml' - name: "Setup Python with cache" @@ -125,7 +167,7 @@ jobs: - name: "Cache examples" uses: actions/cache@v4 - if: steps.changes.outputs.documentation == 'false' || (github.ref == 'refs/heads/main' && !contains(github.ref, 'refs/tags')) + if: ${{ inputs.use_cache_examples && (steps.changes.outputs.documentation != 'true' || env.NOT_ON_RELEASE) }} with: path: doc/source/examples key: Examples-v${{ env.RESET_EXAMPLES_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }} @@ -134,7 +176,7 @@ jobs: - name: "Cache docs build directory" uses: actions/cache@v4 - if: steps.changes.outputs.documentation == 'false' || (github.ref == 'refs/heads/main' && !contains(github.ref, 'refs/tags')) + if: ${{ inputs.use_cache_doc_build && (steps.changes.outputs.documentation != 'true' || env.NOT_ON_RELEASE) }} with: path: doc/_build key: doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }} @@ -143,7 +185,7 @@ jobs: - name: "Cache autosummary" uses: actions/cache@v4 - if: steps.changes.outputs.documentation == 'false' || (github.ref == 'refs/heads/main' && !contains(github.ref, 'refs/tags')) + if: ${{ inputs.use_cache_autosummary && (steps.changes.outputs.documentation != 'true' || env.NOT_ON_RELEASE) }} with: path: doc/source/**/_autosummary/*.rst key: autosummary-v${{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }} @@ -162,16 +204,19 @@ jobs: .ci/waiting_services.sh - name: Install Quarto + if: ${{ inputs.build_cheatsheet }} uses: quarto-dev/quarto-actions/setup@v2 with: tinytex: true - name: Check Quarto Version + if: ${{ inputs.build_cheatsheet }} shell: bash run: | quarto --version - name: "Install Poppler for PDF to PNG conversion" + if: ${{ inputs.build_cheatsheet }} shell: bash run: | sudo apt-get update @@ -180,7 +225,7 @@ jobs: - name: "Build documentation" shell: bash run: | - xvfb-run make -C doc html SPHINXOPTS="-j auto -W --keep-going" + xvfb-run make -C doc ${{ inputs.builder }} SPHINXOPTS="-j auto -W --keep-going" - name: "Substitute defective GIF" shell: bash @@ -195,16 +240,19 @@ jobs: retention-days: 7 - name: "Build PDF Documentation" + if: ${{ inputs.build_pdf }} working-directory: doc shell: bash run: make pdf - name: "Show latex dir" + if: ${{ inputs.build_pdf }} working-directory: doc shell: bash run: ls _build/latex - name: "Upload PDF documentation" + if: ${{ inputs.build_pdf }} uses: actions/upload-artifact@v4 with: name: documentation-pdf diff --git a/.github/workflows/linkchecker.yml b/.github/workflows/linkchecker.yml index bae92c40dcf..cefc0b0b5db 100644 --- a/.github/workflows/linkchecker.yml +++ b/.github/workflows/linkchecker.yml @@ -9,107 +9,31 @@ concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true -env: - ON_CI: True - MAPDL_PACKAGE: ghcr.io/ansys/mapdl - MAPDL_IMAGE_VERSION_DOCS_BUILD: v24.1.0 - MAIN_PYTHON_VERSION: '3.10' - PYANSYS_OFF_SCREEN: True - DPF_START_SERVER: False - DPF_PORT: 21002 - jobs: - linkchecker: - name: Check Links + linkcheck: + name: "Check Links" + uses: ./.github/workflows/doc-build.yml + with: + builder: linkcheck + build_pdf: false + build_cheatsheet: false + use_cache_examples: false + use_cache_doc_build: false + use_cache_autosummary: false + secrets: + license-server: ${{ secrets.LICENSE_SERVER }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + notify: + name: "Notify failed build" + needs: [linkcheck] + if: failure() && github.event_name == 'schedule' runs-on: ubuntu-22.04 - timeout-minutes: 60 - env: - PYMAPDL_PORT: 21000 # default won't work on GitHub runners - PYMAPDL_DB_PORT: 21001 # default won't work on GitHub runners - PYMAPDL_START_INSTANCE: FALSE - ON_DOCUMENTATION: TRUE - SHELLOPTS: "errexit:pipefail" steps: - - name: "Install Git and checkout project" - uses: actions/checkout@v4.2.2 - - - name: "Login in Github container registry" - uses: docker/login-action@v3.4.0 - with: - registry: ghcr.io - username: ${{ secrets.GH_USERNAME }} - password: ${{ secrets.GITHUB_TOKEN }} - - - name: "DPF server activation" - run: | - $(docker pull ghcr.io/ansys/dpf-core:22.2dev && docker run -d --name dpfserver -p ${{ env.DPF_PORT }}:50052 ghcr.io/ansys/dpf-core:22.2dev && echo "DPF Server active on port ${{ env.DPF_PORT }}.") & - - - name: "Pull, launch, and validate MAPDL service" - id: start_mapdl - env: - LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }} - MAPDL_VERSION: ${{ env.MAPDL_IMAGE_VERSION_DOCS_BUILD }} - DISTRIBUTED_MODE: "dmp" - run: | - export INSTANCE_NAME=MAPDL - .ci/start_mapdl.sh &> mapdl_launch.log & export DOCKER_PID=$! - echo "Launching MAPDL service at PID: $DOCKER_PID" - echo "DOCKER_PID=$(echo $DOCKER_PID)" >> $GITHUB_OUTPUT - - - name: "Setup Python" - uses: actions/setup-python@v5 - with: - python-version: ${{ env.MAIN_PYTHON_VERSION }} - - - name: "Install OS packages" - run: | - sudo apt update - sudo apt install zip pandoc libgl1-mesa-glx xvfb texlive-latex-extra latexmk graphviz - - - name: "Test virtual framebuffer" - run: | - pip install -r .ci/requirements_test_xvfb.txt - xvfb-run python .ci/display_test.py - - - name: "Install ansys-mapdl-core" - run: | - pip install . - xvfb-run python -c "from ansys.mapdl import core as pymapdl; print(pymapdl.Report())" - - - name: "Retrieve PyMAPDL version" - id: version - run: | - echo "PYMAPDL_VERSION=$(python -c 'from ansys.mapdl.core import __version__; print(__version__)')" >> $GITHUB_OUTPUT - echo "PyMAPDL version is: $(python -c "from ansys.mapdl.core import __version__; print(__version__)")" - - - name: "Install docs build requirements" - run: | - pip install .[doc] - - - name: "Waiting for the services to be up" - run: | - .ci/waiting_services.sh - - - name: LinkCheck - run: | - xvfb-run make -C doc linkcheck SPHINXOPTS="-j auto -W --keep-going" - - - name: "Display linkchecker results" - if: always() - run: | - echo "::group:: Display linkcher output" && cat doc/*/output.txt && echo "::endgroup::" || echo "Failed to display the output file." - - - name: "Upload HTML Documentation" - uses: actions/upload-artifact@v4 - with: - name: documentation-html - path: doc/_build/html - retention-days: 7 - - - name: "Upload artifacts" - uses: actions/upload-artifact@v4 - if: always() + - name: "Open issue" + uses: jayqi/failed-build-issue-action@v1 with: - name: output - path: doc/**/output.txt - retention-days: 30 \ No newline at end of file + github-token: ${{ secrets.GITHUB_TOKEN }} + title-template: "Failed scheduled linkcheck 🔗 build" + label-name: "Build failed" diff --git a/doc/changelog.d/3850.fixed.md b/doc/changelog.d/3850.fixed.md new file mode 100644 index 00000000000..94948f10063 --- /dev/null +++ b/doc/changelog.d/3850.fixed.md @@ -0,0 +1 @@ +fix: linkchecker \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 63c1562a3b3..23ab6e8e5cb 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -226,6 +226,8 @@ "https://ansyshelp.ansys.com/*", # behind authentication "https://forum.ansys.com/forums/*", # It is detected as broken "https://courses.ansys.com/*", # It is detected as broken + "https://blog.derlin.ch/genetic-algorithms-with-pygad", # Error: Too Many Requests for url + "https://www.mdpi.com/*", # 403 Client Error: Forbidden for url ] linkcheck_anchors_ignore = [ # these anchors are picked by linkcheck as broken but they are not.