Links checker and redirection capabilities (#2090)

* fixing contributing link

* fixing more links

* Improving bug template

* Fixing links

* Fixing make configuration

* Adding anchor ignore.
Adding redirect to krylov example

* more info on old link

* Removing deploy from make.
Fixing link build directory
Specifying the doctrees directory

* fixing link

* Adding it to cicd

* Adding linkchecker workflow - Need to adapt and fix

* Removing linkchecker from main cicd

* Undoing some changes

.github/workflows/linkchecker.yml

@@ -0,0 +1,115 @@
+name: LinkCheck - All files 🔗
+
+on:
+  schedule:
+    - cron: "0 5 * * 0" # Runs at 05:00 on Sunday.
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+
+jobs:
+  linkchecker:
+    name: Check Links
+    runs-on: ubuntu-latest
+    env:
+      PYANSYS_OFF_SCREEN: "True"
+      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@v3
+
+      - name: "Setup Python"
+        uses: actions/setup-python@v4
+        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: "Cache pip"
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: Python-v${{ env.RESET_PIP_CACHE }}-Linux-${{ env.MAIN_PYTHON_VERSION }}-${{ hashFiles('pyproject.toml') }}
+          restore-keys: |
+            Python-v${{ env.RESET_PIP_CACHE }}-Linux-${{ env.MAIN_PYTHON_VERSION }}
+
+      - 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: "Login in Github container registry"
+        uses: docker/[email protected]
+        with:
+          registry: ghcr.io
+          username: ${{ secrets.GH_USERNAME }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: "Pull, launch, and validate MAPDL service"
+        run: .ci/start_mapdl.sh
+        env:
+          LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
+          MAPDL_IMAGE: '${{ env.DOCKER_PACKAGE }}:${{ env.DOCKER_IMAGE_VERSION_DOCS_BUILD }}'
+
+      - 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: "Cache examples"
+        uses: actions/cache@v3
+        with:
+          path: doc/source/examples
+          key: Examples-v${{ env.RESET_EXAMPLES_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }}
+          restore-keys: |
+            Examples-v${{ env.RESET_EXAMPLES_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}
+
+      - name: "Cache docs build directory"
+        uses: actions/cache@v3
+        with:
+          path: doc/_build
+          key: doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }}
+          restore-keys: |
+            doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}
+
+      - name: "Cache autosummary"
+        uses: actions/cache@v3
+        with:
+          path: doc/source/**/_autosummary/*.rst
+          key: autosummary-v${{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}-${{ github.sha }}
+          restore-keys: |
+            autosummary-v${{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYMAPDL_VERSION }}
+
+      - name: "Install docs build requirements"
+        run: |
+          pip install .[doc]
+
+      - 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: LinkCheck
+        run: |
+          make -C doc linkcheck
+
+      - name: "Display linkchecker results"
+        run: |
+          echo "::group:: Display linkcher output" && cat doc/*/output.txt && echo "::endgroup::" || echo "Failed to display the output file."
+

CONTRIBUTING.md

@@ -11,6 +11,6 @@ questions or submissions to this repository.
 
 
 For contributing to this project, please refer to the [PyAnsys Developer's Guide].
-Further information about contributing to PyMAPDL can be found in [Contributing](https://mapdl.docs.pyansys.com/contribution_and_api/index.html).
+Further information about contributing to PyMAPDL can be found in [Contributing](https://mapdl.docs.pyansys.com/version/stable/getting_started/contribution.html).
 
 [PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/

README.rst

@@ -57,7 +57,7 @@ or in batch mode on Windows, Linux, and even Mac OS.
 Documentation and issues
 ------------------------
 For more information, see the `Documentation <https://mapdl.docs.pyansys.com>`_ page.
-For some examples, see the `Examples gallery <https://mapdl.docs.pyansys.com/examples/index.html>`_.
+For some examples, see the `Examples gallery <https://mapdl.docs.pyansys.com/version/stable/examples/index.html>`_.
 
 Feel free to post issues and other questions at `PyMAPDL Issues
 <https://github.com/pyansys/pymapdl/issues>`_.  This is the best place

doc/Makefile

@@ -2,11 +2,12 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
 LINKCHECKDIR  = $(BUILDDIR)/linkcheck
+SPHINXOPTS    = -j auto --color
+LINKCHECKOPTS = -d $(BUILDDIR)/.doctrees -W --keep-going --color
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -41,24 +42,7 @@ pdf:
 	(test -f $(BUILDDIR)/latex/pymapdl-Documentation-*.pdf && echo pdf exists) || exit 1
 
 linkcheck:
-	@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" -D nitpicky=1 -d _build/doctrees . $(LINKCHECKDIR)
+	@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(LINKCHECKOPTS)
 	@echo
 	@echo "Check finished. Report is in $(LINKCHECKDIR)."
 
-# manually deploy to https://github.com/pyansys/pymapdl-docs
-# WARNING: Use with care as this overwrites history of gh-pages
-deploy: 
-	@echo "*** Warning ***"
-	@echo "You are about to deploy to 'PyMAPDL docs'."
-	@echo "This overwrites the history of gh-pages."
-	@echo "Are you sure? [y/N] " && read ans && [ $${ans:-N} = y ]
-	@echo "Deploying..."
-	touch $(BUILDDIR)/html/.nojekyll
-	echo "mapdl.docs.pyansys.com" >> build/html/CNAME
-	cd $(BUILDDIR)/html && git init
-	cd $(BUILDDIR)/html && git add .
-	cd $(BUILDDIR)/html && git checkout -b gh-pages
-	cd $(BUILDDIR)/html && git commit -am "manual build"
-	cd $(BUILDDIR)/html && git remote add origin https://github.com/pyansys/pymapdl-docs
-	cd $(BUILDDIR)/html && git push -u origin gh-pages --force
-	rm -rf $(BUILDDIR)/html/.git

doc/source/conf.py

@@ -168,6 +168,7 @@
 
 # make rst_epilog a variable, so you can add other epilog parts to it
 rst_epilog = ""
+
 # Read link all targets from file
 with open("links.rst") as f:
     rst_epilog += f.read()
@@ -178,6 +179,22 @@
 with open("substitutions.rst") as f:
     rst_epilog += f.read()
 
+
+# Setting redicts
+redirects = {
+    # old linK: https://dev.mapdl.docs.pyansys.com/user_guide/krylov.html
+    "user_guide/krylov": "examples/extended_examples/Krylov/krylov_example"
+}
+
+# Broken anchors:
+linkcheck_anchors_ignore = [
+    # these anchors are picked by linkcheck as broken but thye are not.
+    "firewall-rules",
+    "pyvista.Plotter",
+    "pyvista.UnstructuredGrid",
+    "pyvista.Plotter.show",
+]
+
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 

doc/source/getting_started/wsl.rst

@@ -142,7 +142,7 @@ MAPDL installation can communicate with the Windows hosts. If you are having
 problems after setting the firewall rules, you might have to turn off the Windows
 firewall for the WSL ethernet virtual interface. This might pose some unknown
 side effects and security risk so use it with caution. For more information, see
-`Disabling Firewall on WSL Ethernet <disabling_firewall_on_wsl_>`_.
+:ref:`Disable firewall on WSL ethernet <disable_firewall_on_wsl_ethernet_section>`.
 
 
 Set up an environmental variable in WSL that points to Windows host license server
@@ -324,6 +324,7 @@ install. When you do so, you must use the ``-productfile`` argument to specify t
 full path to the ``options`` file.
 
 
+.. _disable_firewall_on_wsl_ethernet_section:
 
 Disable firewall on WSL ethernet
 ================================
@@ -348,7 +349,9 @@ This method does not show a notification:
     powershell.exe -Command "Set-NetFirewallProfile -DisabledInterfaceAliases \"vEthernet (WSL)\""
 
 
-Link: `Disable firewall on WSL ethernet <disabling_firewall_on_wsl_>`_
+**Reference:** 
+The information has been obtained from `WSL Windows Toolbar Launcher repository <WSL_Windows_Toolbar_Launcher_>`_.
+More specifically from the *Troubleshooting* section `Firewall rules <disabling_firewall_on_wsl_>`_
 
 Port forwarding on Windows 10
 =============================

doc/source/links.rst

@@ -3,25 +3,25 @@
 .. The substitution for the actual value is made on conf.py file.
 
 .. #Pyansys
-.. _pyansys: https://docs.pyansys.com/dev/
+.. _pyansys: https://docs.pyansys.com/version/dev/
 .. _pyansys_support: [email protected]
 .. _pyansys_core: [email protected]
 
 .. #Other projects
 .. _dpf_core_gh: https://github.com/pyansys/DPF-Core
 .. _dpf_post_gh: https://github.com/pyansys/DPF-Post
-.. _dpf_core_docs: https://dpf.docs.pyansys.com/dev/
-.. _dpf_post_docs: https://post.docs.pyansys.com/dev/
+.. _dpf_core_docs: https://dpf.docs.pyansys.com
+.. _dpf_post_docs: https://post.docs.pyansys.com
 .. _legacy_reader_docs: https://reader.docs.pyansys.com/
 .. _example_data_repo: https://github.com/pyansys/example-data
 .. _ansys_tools_path: http://path.tools.docs.pyansys.com/
 .. _pyansys_math: https://math.docs.pyansys.com/version/stable/
 .. _pyansys_math_api: https://math.docs.pyansys.com/version/stable/api/index.html
 
 .. #PyAnsys Developer Guide
-.. _dev_guide_pyansys: https://dev.docs.pyansys.com/dev/
-.. _dev_guide_contributing: https://dev.docs.pyansys.com/dev/how-to/contributing.html
-.. _dev_guide_coding_style: https://dev.docs.pyansys.com/dev/coding-style/index.html
+.. _dev_guide_pyansys: https://dev.docs.pyansys.com
+.. _dev_guide_contributing: https://dev.docs.pyansys.com/how-to/contributing.html
+.. _dev_guide_coding_style: https://dev.docs.pyansys.com/coding-style/index.html
 
 .. #Other libraries
 .. _pyvista_docs: https://docs.pyvista.org/version/stable/
@@ -106,6 +106,8 @@
 .. _gh_centos_wsl_1: https://github.com/wsldl-pg/CentWSL/
 .. _gh_centos_wsl_2: https://github.com/mishamosher/CentOS-WSL/
 .. _codecov: https://github.com/codecov
+.. _WSL_Windows_Toolbar_Launcher: https://github.com/cascadium/wsl-windows-toolbar-launcher
+.. _disabling_firewall_on_wsl: https://github.com/cascadium/wsl-windows-toolbar-launcher#firewall-rules
 
 .. #PyMAPDL related
 .. _pymapdl_main: pymapdl_docs_
@@ -124,11 +126,11 @@
 .. _pymapdl_examples: https://github.com/pyansys/pymapdl/tree/main/examples
 .. _pymapdl_2d_plate_with_a_hole: https://github.com/pyansys/pymapdl/blob/main/examples/00-mapdl-examples/2d_plate_with_a_hole.py
 .. _pymapdl_doc_2d_plate_with_a_hole: https://mapdl.docs.pyansys.com/version/stable/examples/gallery_examples/00-mapdl-examples/2d_plate_with_a_hole.html
-.. _pymapdl_doc_krylov_example: https://dev.mapdl.docs.pyansys.com/version/stable/examples/extended_examples/Krylov/krylov_example.html
+.. _pymapdl_doc_krylov_example: https://mapdl.docs.pyansys.com/version/stable/examples/extended_examples/Krylov/krylov_example.html
 .. _pymapdl_doc_krylov_example_rst: https://raw.githubusercontent.com/pyansys/pymapdl/main/doc/source/examples/extended_examples/Krylov/krylov_example.rst
 .. _pymapdl_doc_source: https://github.com/pyansys/pymapdl/tree/main/doc/source
 .. _pymapdl_techdemo_28_rst: https://raw.githubusercontent.com/pyansys/pymapdl-examples/main/doc/source/technology_showcase_examples/techdemo-28/ex_28-tecfricstir.rst
-.. _pymapdl_techdemo_28: https://examples.mapdl.docs.pyansys.com/version/stable/technology_showcase_examples/techdemo-28/ex_28-tecfricstir.html
+.. _pymapdl_techdemo_28: https://examples.mapdl.docs.pyansys.com/technology_showcase_examples/techdemo-28/ex_28-tecfricstir.html
 .. _pymapdl_docker_dir: https://github.com/pyansys/pymapdl/blob/main/docker
 .. _pymapdl_docker_compose_base: https://github.com/pyansys/pymapdl/blob/main/docker/docker-compose.yml
 .. _pymapdl_docker_compose_local: https://github.com/pyansys/pymapdl/blob/main/docker/docker-compose.local.yml

examples/00-mapdl-examples/basic_dpf_example.py

@@ -5,7 +5,7 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This example is adapted from
-`Basic DPF-Core Usage Example <https://dpf.docs.pyansys.com/examples/00-basic/00-basic_example.html>`_
+`Basic DPF-Core Usage Example <https://dpf.docs.pyansys.com/version/stable/examples/00-basic/00-basic_example.html>`_
 and it shows how to open a result file in `DPF <https://dpf.docs.pyansys.com/>`_ and do some
 basic postprocessing.
 

examples/00-mapdl-examples/cyclic_analysis.py

@@ -169,7 +169,7 @@ def gen_sector(mapdl, sectors):
 #
 # For more details regarding cyclic result post processing, see:
 # - `Understanding Nodal Diameters from a Cyclic Model Analysis <https://reader.docs.pyansys.com/examples/01-cyclic_results/academic_sector_nd.html>`_
-# - `Modal Cyclic Symmetry Example <https://dpf.docs.pyansys.com/examples/02-modal-harmonic/01-modal_cyclic.html>`_
+# - `Cyclic symmetry examples <https://dpf.docs.pyansys.com/version/stable/examples/11-cyclic-symmetry/index.html>`_
 
 # grab the result object from MAPDL
 result = mapdl.result

src/ansys/mapdl/core/_commands/solution/load_step_operations.py

@@ -62,7 +62,7 @@ def lsread(self, lsnum="", **kwargs):
 
         .. warning:: This command can only run in non-interactive mode.
             Please visit `Unsupported "Interactive" Commands
-            <https://mapdl.docs.pyansys.com/user_guide/mapdl.html#unsupported-interactive-commands>`_
+            <https://mapdl.docs.pyansys.com/version/stable/user_guide/mapdl.html#unsupported-interactive-commands>`_
             for further information.
 
         APDL Command: LSREAD