feat: script for automatic link update when releasing (#297)

* fix: cleanup links.rst

* fix: PySeascape links

* feat: automatically replace links

* fix: pre-commit

* fix: typo

* feat: improve robustness

* fix: pre-commit

* fix: typo

* docs: module docstring

* Apply suggestions from code review

Author: RobPasMue

doc/source/getting_started.rst

@@ -3,7 +3,7 @@ Getting started
 
 PyAnsys libraries fall into two categories:
 
-- Wrappers over products like `MAPDL <https://www.ansys.com/training-center/course-catalog/structures/ansys-mechanical-advanced-use-of-mapdl-in-mechanical>`_, `Fluent <https://www.ansys.com/products/fluids/ansys-fluent>`_, or `AEDT <https://www.ansys.com/products/electronics/ansys-maxwell>`_
+- Wrappers over products like `MAPDL <mapdl_course_>`_, `Fluent <ansys_fluent_page_>`_, or `AEDT <ansys_aedt_page_>`_
 - Supporting libraries like `DPF <dpf_post_gh_>`_
 
 Most PyAnsys packages require a local installation of Ansys. The version
@@ -15,7 +15,7 @@ the host machine.
 
 For more information on getting a licensed copy of Ansys, visit `Ansys
 <ansys_>`_. If you are a student, consider installing a student version by
-visiting `Ansys for Students <https://www.ansys.com/academic/students>`_.
+visiting `Ansys for Students <ansys_students_>`_.
 
 
 ************
@@ -44,7 +44,7 @@ User mode installation
 ^^^^^^^^^^^^^^^^^^^^^^
 
 Before installing ``pyansys`` in user mode, ensure that you have the latest
-version of `pip <https://pypi.org/project/pip/>`_ with:
+version of `pip`_ with:
 
 .. code:: bash
 
@@ -74,9 +74,8 @@ Offline mode installation
 
 If you lack an internet connection on your installation machine, the
 recommended way of installing the ``pyansys`` metapackage is downloading the
-wheelhouse archive from the `Releases Page
-<https://github.com/ansys/pyansys/releases>`_ for your corresponding machine
-architecture.
+wheelhouse archive from the `Releases Page <pyansys_releases_>`_ for your
+corresponding machine architecture.
 
 Each wheelhouse archive contains all the Python wheels necessary to install
 ``pyansys`` metapackage from scratch on Windows, Linux, and MacOS from Python
@@ -93,7 +92,7 @@ it with the following:
 
 If you're on Windows with Python 3.9, unzip to a wheelhouse directory and install using the same command as above.
 
-Consider installing using a `virtual environment <https://docs.python.org/3/library/venv.html>`_.
+Consider installing using a `virtual environment <venv_docs_>`_.
 
 
 Versioning system

doc/source/links.rst

@@ -1,118 +1,11 @@
-.. #Pyansys
-.. _pyansys: https://docs.pyansys.com
-.. _pyansys_support: [email protected]
-
-.. #Other projects
-.. _dpf_core_gh: https://github.com/ansys/pydpf-core
+.. #Getting started
+.. _mapdl_course: https://www.ansys.com/training-center/course-catalog/structures/ansys-mechanical-advanced-use-of-mapdl-in-mechanical
+.. _ansys_fluent_page: https://www.ansys.com/products/fluids/ansys-fluent
+.. _ansys_aedt_page: https://www.ansys.com/products/electronics/ansys-maxwell
 .. _dpf_post_gh: https://github.com/ansys/pydpf-post
-.. _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/ansys/example-data
-
-.. #PyAnsys Developer Guide
-.. _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
-.. _jupyter: https://jupyter.org/
 .. _grpc: https://grpc.io/
-.. _numpy_docs: https://numpy.org/doc/stable/
-.. _matplotlib_docs: https://matplotlib.org/stable/contents.html
-.. _matplotlib_main: https://matplotlib.org
-.. _precommit: https://pre-commit.com/
-.. _gmsh: https://gmsh.info/
-.. _scipy_docs: https://docs.scipy.org/doc/scipy/reference/
-.. _docker: https://www.docker.com/
-
-
-.. #Ansys
 .. _ansys: https://www.ansys.com/
-.. _ansys_student_version: https://www.ansys.com/academic/students
-.. _ansys_innovation_space: https://courses.ansys.com/
-.. _ansys_platform_support: https://www.ansys.com/solutions/solutions-by-role/it-professionals/platform-support
-.. _ansys_current_release: https://download.ansys.com/Current%20Release
-
-.. # TechDemos related
-.. _tech_demo_intro: https://ansyshelp.ansys.com/Views/Secured/corp/v212/en/ans_tec/tecintro.html
-.. _tech_demo_repo: https://github.com/ansys/pymapdl-examples
-.. _tech_demos_doc: https://examples.mapdl.docs.pyansys.com/
-
-.. #Ansys internal documentation
-.. _ansys_help: https://ansyshelp.ansys.com
-.. _ansys_installation_and_licensing: https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/prod_page.html?pn=Installation%20and%20Licensing&pid=InstallationAndLicensing&lang=en
-.. _ansys_parallel_computing_guide: https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v222/en/ans_dan/dantoc.html
-
-.. # Ansys Structural Guide links:
-.. _ansys_krylov_sweep_harmonic_analysis: https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/corp/v222/en/ans_str/str_Krysweep.html
-
-.. #Ansys learning
-.. _course_intro_python: https://courses.ansys.com/index.php/courses/intro-to-python/
-.. _course_getting_started_pymapdl: https://courses.ansys.com/index.php/courses/getting-started-with-pymapdl/
-.. _course_intro_apdl: https://courses.ansys.com/index.php/courses/intro-to-ansys-mechanical-apdl-scripting/
-
-.. #External links
-.. _padt_post: https://www.padtinc.com/2022/07/18/ansys-scripting-python-p1-solve-post/
-.. _padt_licensing: https://www.padtinc.com/blog/15271-2/
-.. _install_wsl_microsoft: https://docs.microsoft.com/en-us/windows/wsl/install/
-.. _WikipediaWSL: https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux
-.. _What_is_the_Windows_Subsystem_for_Linux: https://docs.microsoft.com/en-us/windows/wsl/about
-.. _open_port_windows_10: https://answers.microsoft.com/en-us/windows/forum/all/how-to-open-port-in-windows-10-firewall/f38f67c8-23e8-459d-9552-c1b94cca579a/
-.. _disabling_firewall_on_wsl: https://github.com/cascadium/wsl-windows-toolbar-launcher#firewall-rules
-.. _article_good_unit_test: https://stackoverflow.com/questions/61400/what-makes-a-good-unit-test
-.. _vscode_attach_to_container: https://code.visualstudio.com/docs/devcontainers/attach-container
-.. _ubuntu_firewall: https://ubuntu.com/server/docs/security-firewall
-
-.. #Github links:
-.. _gh_creating_pat: https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
-.. _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
-
-.. #PyMAPDL related
-.. _pymapdl_main: pymapdl_docs_
-.. _pymapdl_pypi: https://pypi.org/project/ansys-mapdl-core/
-.. _pymapdl_releases: https://github.com/ansys/pymapdl/releases
-.. _pymapdl_run_ubuntu: https://mapdl.docs.pyansys.com/troubleshoot/troubleshoot.html?#ubuntu
-.. _pymapdl_issues: https://github.com/ansys/pymapdl/issues
-.. _pymapdl_repo: https://github.com/ansys/pymapdl
-.. _pymapdl_docs: https://mapdl.docs.pyansys.com/
-.. _pymapdl_dev_docs: https://dev.mapdl.docs.pyansys.com/
-.. _pymapdl_discussions: https://github.com/ansys/PyMAPDL/discussions
-.. _pymapdl_cheatsheet: ./_assets/Cheat_Sheet_PyMAPDL.pdf
-.. _pymapdl_tests: https://github.com/ansys/pymapdl/tree/main/tests
-.. _pymapdl_test_math: https://github.com/ansys/pymapdl/blob/main/tests/test_math.py
-.. _pymapdl_user_guide_math: https://mapdl.docs.pyansys.com/user_guide/math.html
-.. _licensing_guide_pdf: ./_assets/lic_guide.pdf
-.. _mapdl_fixture: https://github.com/ansys/pymapdl/blob/fb5fb8b6201253f1bd56bdabee60a29abee8c7d8/tests/conftest.py#L254
-.. _pymapdl_examples: https://github.com/ansys/pymapdl/tree/main/examples
-.. _pymapdl_2d_plate_with_a_hole: https://github.com/ansys/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/examples/gallery_examples/00-mapdl-examples/2d_plate_with_a_hole.html
-.. _pymapdl_doc_krylov_example: https://dev.mapdl.docs.pyansys.com/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/ansys/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/technology_showcase_examples/techdemo-28/ex_28-tecfricstir.html
-.. _pymapdl_docker_dir: https://github.com/ansys/pymapdl/blob/main/docker
-.. _pymapdl_docker_compose_base: https://github.com/ansys/pymapdl/blob/main/docker/docker-compose.yml
-.. _pymapdl_docker_compose_local: https://github.com/ansys/pymapdl/blob/main/docker/docker-compose.local.yml
-.. _pymapdl_docker_compose_license_server: https://github.com/ansys/pymapdl/blob/main/docker/docker-compose.license_server.yml
-
-.. #Python
-.. _using_venv: https://docs.python.org/3/library/venv.html
-.. _conda: https://conda.io
-.. _pytest: https://docs.pytest.org/en/7.2.x/
-.. _pytest_usage: https://docs.pytest.org/en/7.2.x/how-to/usage.html#specifying-which-tests-to-run
-
-.. #Julia
-.. _julia: https://julialang.org/
-.. _julia_windows: https://julialang.org/downloads/platform/#windows
-.. _julia_linux_and_freebsd: https://julialang.org/downloads/platform/#linux_and_freebsd
-.. _julia_macos: https://julialang.org/downloads/platform/#macos
-.. _pycall: https://github.com/JuliaPy/PyCall.jl
-
-.. # Ansys forums
-.. _ansys_forum: https://forum.ansys.com/
-.. _af_licensing_windows_ubuntu: https://forum.ansys.com/forums/topic/licensing-2022-r2-linux-ubuntu-and-also-windows/
+.. _ansys_students: https://www.ansys.com/academic/students
+.. _pip: https://pypi.org/project/pip/
+.. _pyansys_releases: https://github.com/ansys/pyansys/releases
+.. _venv_docs: https://docs.python.org/3/library/venv.html

tools/links.py

@@ -0,0 +1,153 @@
+"""
+Script for automatic replacement of released links.
+
+Usage is very simple. Just run the script.
+
+.. code:: python
+
+    python links.py
+"""
+
+import os
+import re
+
+ROOT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+"""Root directory of the project relative to this file."""
+
+PYPROJECT_TOML_FILE = os.path.join(ROOT_DIR, "pyproject.toml")
+"""Path to pyproject.toml file."""
+
+DOCS_DIRECTORY = os.path.join(ROOT_DIR, "doc", "source")
+"""Path to the documentation source directory"""
+
+LINKS = {
+    "ansys-mapdl-core": "https://mapdl.docs.pyansys.com/version/stable",
+    "ansys-mapdl-reader": "https://reader.docs.pyansys.com/version/stable",
+    "ansys-dpf-core": "https://dpf.docs.pyansys.com/version/stable",
+    "ansys-dpf-post": "https://post.docs.pyansys.com/version/stable",
+    "ansys-dpf-gate": None,
+    "ansys-dpf-composites": "https://composites.dpf.docs.pyansys.com/version/stable",  # noqa: E501
+    "ansys-fluent-core": "https://fluent.docs.pyansys.com/version/stable",
+    "ansys-fluent-visualization": "https://visualization.fluent.docs.pyansys.com/version/stable",  # noqa: E501
+    "ansys-fluent-parametric": "https://parametric.fluent.docs.pyansys.com/version/stable",  # noqa: E501
+    "pyaedt": "https://aedt.docs.pyansys.com/version/stable",
+    "ansys-platform-instancemanagement": None,
+    "ansys-grantami-bomanalytics": "https://bomanalytics.grantami.docs.pyansys.com/version/stable",  # noqa: E501
+    "ansys-grantami-recordlists": "https://recordlists.grantami.docs.pyansys.com/version/stable",  # noqa: E501
+    "ansys-openapi-common": None,
+    "ansys-seascape": "https://seascape.docs.pyansys.com/version/stable",
+    "ansys-sherlock-core": "https://sherlock.docs.pyansys.com/version/stable",
+    "ansys-meshing-prime": "https://prime.docs.pyansys.com/version/stable",
+    "pytwin": "https://twin.docs.pyansys.com/version/stable",
+    "ansys-systemcoupling-core": "https://systemcoupling.docs.pyansys.com/version/stable",  # noqa: E501
+    "ansys-motorcad-core": "https://motorcad.docs.pyansys.com/version/stable",
+    "ansys-math-core": "https://math.docs.pyansys.com/version/stable",
+    "ansys-optislang-core": "https://optislang.docs.pyansys.com/version/stable",  # noqa: E501
+    "ansys-mechanical-core": "https://mechanical.docs.pyansys.com/version/stable",  # noqa: E501
+}
+"""Dictionary with PyAnsys packages and their multi-version docs site."""
+
+
+def retrieve_major_minor(package: str):
+    """Extract the major and minor version of a pinned package.
+
+    Notes
+    -----
+    This function navigates to the package's pyproject.toml file
+
+    and processes it to retrieve the desired major, minor version.
+
+
+    Parameters
+    ----------
+    package : str
+        The package to be searched for.
+
+
+    Returns
+    -------
+    tuple of (int, int)
+        The major and minor versions of the package.
+
+    """
+    with open(PYPROJECT_TOML_FILE, "r") as file:
+        content = file.read()
+        pattern = r"\b" + re.escape(package) + r"==(\d+)\.(\d+)"
+        match = re.search(pattern, content)
+
+        if match:
+            major_version = int(match.group(1))
+            minor_version = int(match.group(2))
+            return (major_version, minor_version)
+
+    return (None, None)
+
+
+def search_and_replace(link: str, new_link: str):
+    """Replace existing link with the newly provided link.
+
+    Parameters
+    ----------
+    link : str
+        The link to be searched for.
+    new_link : str
+        The link to replace the existing one.
+    """
+    # Traverse the docs directory
+    for root, _, files in os.walk(DOCS_DIRECTORY):
+        # Skip the _static subdirectory
+        if "_static" in root.split(os.sep):
+            continue
+
+        # Process the files
+        for file in files:
+            file_path = os.path.join(root, file)
+            with open(file_path, "r") as f:
+                content = f.read()
+
+            # Search for the link in the content, replace and save
+            if link in content:
+                new_content = content.replace(link, new_link)
+
+                with open(file_path, "w") as f:
+                    f.write(new_content)
+
+                print(f"Replaced '{link}' with '{new_link}' in file: {file_path}")  # noqa: E501
+
+
+def released_docs():
+    """Update links for released documentation.
+
+    Notes
+    -----
+    Links are expected to point to a certain version when released
+    inside the metapackage, and not to the latest stable version. This
+    module takes care of updating the links automatically. The script has to
+    be run locally and the changes have to be committed to the release branch
+    prior to releasing.
+    """
+    # Loop over all the above defined packages
+    for key, value in LINKS.items():
+        # Packages that are not adapted to multi-version have a None
+        # link associated as its value... skip them.
+        if value is None:
+            continue
+
+        # Retrieve the major and minor versions of the package
+        major, minor = retrieve_major_minor(key)
+
+        if major is None and minor is None:
+            # No match found for the link... throw message
+            print(f"Error retrieving minor/major version of {key}... Skipping.")  # noqa: E501
+            continue
+
+        # Define the new link
+        link_root = value.split("/version/")[0]
+        new_link = f"{link_root}/version/{major}.{minor}"
+
+        # Search and replace through all our docs links
+        search_and_replace(value, new_link)
+
+
+if __name__ == "__main__":
+    released_docs()