Using custom edit link

.github/workflows/ci.yml

@@ -31,10 +31,10 @@ env:
   # You should go up in number, if you go down (or repeat a previous value)
   # you might end up reusing a previous cache if it haven't been deleted already.
   # It applies 7 days retention policy by default.
-  RESET_PIP_CACHE: 1
-  RESET_EXAMPLES_CACHE: 1
-  RESET_DOC_BUILD_CACHE: 1
-  RESET_AUTOSUMMARY_CACHE: 1
+  RESET_PIP_CACHE: 2
+  RESET_EXAMPLES_CACHE: 2
+  RESET_DOC_BUILD_CACHE: 2
+  RESET_AUTOSUMMARY_CACHE: 2
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

doc/source/_templates/edit-this-page.html

@@ -0,0 +1,16 @@
+{% if sourcename is defined and theme_use_edit_page_button and page_source_suffix %}
+  {% set src = sourcename.split('.') %}
+  <div class="tocsection editthispage">
+    <a href="{{ fix_edit_link_button(get_edit_provider_and_url()[1]) }}">
+      <i class="fa-solid fa-pencil"></i>
+      {% set provider = get_edit_provider_and_url()[0] %}
+      {% block edit_this_page_text %}
+        {% if provider %}
+          {% trans provider=provider %}Edit on {{ provider }}{% endtrans %}
+        {% else %}
+          {% trans %}Edit{% endtrans %}
+        {% endif %}
+      {% endblock %}
+    </a>
+  </div>
+{% endif %}

doc/source/api/helper.rst

@@ -5,16 +5,20 @@ Helper functions
 These methods simplify launching MAPDL, converting existing scripts,
 or automating other tasks.
 
-.. currentmodule:: ansys.mapdl.core
+
+.. currentmodule:: ansys.mapdl.core.convert
 
 .. autosummary::
    :toctree: _autosummary
-
-   launch_mapdl
+
    convert_apdl_block
    convert_script
+
+
+.. currentmodule:: ansys.mapdl.core.misc
+
+.. autosummary::
+   :toctree: _autosummary
+
    Information
-   change_default_ansys_path
-   find_ansys
-   close_all_local_instances
-   save_ansys_path
+

doc/source/api/launcher.rst

@@ -6,14 +6,27 @@ Various PyMAPDL specific launcher commands.
 Most of these commands are called from the
 library `ansys-tools-path <ansys_tools_path_>`_.
 
-.. currentmodule:: ansys.mapdl.core
+.. currentmodule:: ansys.mapdl.core.launcher
 
 .. autosummary::
    :toctree: _autosummary
 
+   get_default_ansys
+   get_default_ansys_path
+   get_default_ansys_version
+   launch_mapdl
+   close_all_local_instances
+
+
+``ansys-tools-path`` functions
+------------------------------
+
+.. currentmodule:: ansys.tools.path
+
+.. autosummary::
+   :toctree: _autosummary
+
    change_default_ansys_path
-   get_available_ansys_installations
-   launcher.get_default_ansys
-   launcher.get_default_ansys_path
-   launcher.get_default_ansys_version
+   find_ansys
    save_ansys_path
+   get_available_ansys_installations

doc/source/conf.py

@@ -1,15 +1,18 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
 import os
+from typing import Any, Dict
 import warnings
 
 from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
 import numpy as np
 import pyvista
+from sphinx.application import Sphinx
 from sphinx_gallery.sorting import FileNameSortKey
 
 from ansys.mapdl import core as pymapdl
 from ansys.mapdl.core import __version__
+from ansys.mapdl.core.docs import linkcode_resolve
 
 # Manage errors
 pyvista.set_error_output_file("errors.txt")
@@ -47,6 +50,17 @@
 release = version = __version__
 cname = os.getenv("DOCUMENTATION_CNAME", "mapdl.docs.pyansys.com")
 
+REPOSITORY_NAME = "pymapdl"
+USERNAME = "pyansys"
+BRANCH = "main"
+
+
+DEFAULT_EXAMPLE_EXTENSION = "py"
+GALLERY_EXAMPLES_PATH = "examples/gallery_examples"
+EXAMPLES_ROOT = "examples"
+EXAMPLES_PATH_FOR_DOCS = f"../../{EXAMPLES_ROOT}/"
+DOC_PATH = "doc/source"
+SEARCH_HINTS = ["def", "class"]
 
 # -- General configuration ---------------------------------------------------
 extensions = [
@@ -142,7 +156,7 @@
     "Thumbs.db",
     ".DS_Store",
     # because we include this in examples/index.rst
-    "examples/gallery_examples/index.rst",
+    f"{GALLERY_EXAMPLES_PATH}/index.rst",
     "links.rst",
     "substitutions.rst",
 ]
@@ -173,11 +187,11 @@
     # convert rst to md for ipynb
     "pypandoc": True,
     # path to your examples scripts
-    "examples_dirs": ["../../examples/"],
+    "examples_dirs": [EXAMPLES_PATH_FOR_DOCS],
     # path where to save gallery generated examples
-    "gallery_dirs": ["examples/gallery_examples"],
+    "gallery_dirs": [GALLERY_EXAMPLES_PATH],
     # Pattern to search for example files
-    "filename_pattern": r"\.py",
+    "filename_pattern": r"\." + DEFAULT_EXAMPLE_EXTENSION,
     # Remove the "Download all examples" button from the top level gallery
     "download_all_examples": False,
     # Sort gallery example by file name instead of number of lines (default)
@@ -190,6 +204,7 @@
     "ignore_pattern": "flycheck*",
     "thumbnail_size": (350, 350),
 }
+# ---
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -198,7 +213,7 @@
 html_logo = pyansys_logo_black
 html_theme_options = {
     "analytics": {"google_analytics_id": "G-JQJKPV6ZVB"},
-    "github_url": "https://github.com/pyansys/pymapdl",
+    "github_url": f"https://github.com/{USERNAME}/{REPOSITORY_NAME}",
     "show_prev_next": False,
     "show_breadcrumbs": True,
     "collapse_navigation": True,
@@ -209,12 +224,12 @@
     "icon_links": [
         {
             "name": "Support",
-            "url": "https://github.com/pyansys/pymapdl/discussions",
+            "url": f"https://github.com/{USERNAME}/{REPOSITORY_NAME}/discussions",
             "icon": "fa fa-comment fa-fw",
         },
         {
             "name": "Contribute",
-            "url": "https://mapdl.docs.pyansys.com/dev/getting_started/contribution.html",
+            "url": "https://mapdl.docs.pyansys.com/version/dev/getting_started/contribution.html",
             "icon": "fa fa-wrench",
         },
     ],
@@ -226,11 +241,13 @@
 
 html_context = {
     "display_github": True,  # Integrate GitHub
-    "github_user": "pyansys",
-    "github_repo": "pymapdl",
-    "github_version": "main",
-    "doc_path": "doc/source",
+    "github_user": USERNAME,
+    "github_repo": REPOSITORY_NAME,
+    "github_version": BRANCH,
+    "doc_path": DOC_PATH,
 }
+html_show_sourcelink = False
+
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
@@ -305,8 +322,59 @@
 epub_exclude_files = ["search.html"]
 
 
-# Adding apdl syntax highlighting
-def setup(app):
+def setup_to_py(
+    app: Sphinx, pagename: str, templatename: str, context, doctree
+) -> None:
+    """Add a function that jinja can access for returning an "edit this page" link pointing to `main`."""
+
+    def fix_edit_link_button(link: str) -> str:
+        """Transform "edit on github" links and make sure they always point to the main branch.
+
+        Args:
+            link: the link to the github edit interface
+
+        Returns:
+            the link to the tip of the main branch for the same file
+        """
+        # Create custom 'edit' URLs for API modules since they are dynamically generated.
+        doc_path = "/".join(link.split("/")[:-1])
+        file_name = link.split("/")[-1]
+
+        if GALLERY_EXAMPLES_PATH in doc_path:
+            # We are in a python example
+            doc_path = doc_path.replace(
+                f"{DOC_PATH}/{GALLERY_EXAMPLES_PATH}", EXAMPLES_ROOT
+            )
+            file_name = (
+                os.path.basename(file_name).replace(source_suffix, "")
+                + f".{DEFAULT_EXAMPLE_EXTENSION}"
+            )
+            return f"{doc_path}/{file_name}"
+
+        elif "_autosummary" in link:
+            # This is an API example
+            fullname = link.split("_autosummary")[1][1:]
+            return linkcode_resolve(
+                "py", {"module": "ansys.mapdl.core", "fullname": fullname}, edit=True
+            )
+
+        else:
+            return link
+
+    context["fix_edit_link_button"] = fix_edit_link_button
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add custom configuration to sphinx app.
+
+    Args:
+        app: the Sphinx application
+    Returns:
+        the 2 parallel parameters set to ``True``.
+    """
+    app.connect("html-page-context", setup_to_py)
+
+    # Adding apdl syntax highlighting
     from pygments.lexers.apdlexer import apdlexer
     from pygments.lexers.julia import JuliaLexer
 
@@ -316,3 +384,8 @@ def setup(app):
 
     # Julia lexer
     app.add_lexer("julia", JuliaLexer)
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

src/ansys/mapdl/core/docs.py

@@ -0,0 +1,86 @@
+import inspect
+import sys
+
+
+def linkcode_resolve(domain, info, edit=False):
+    """Determine the URL corresponding to a Python object.
+
+    Parameters
+    ----------
+    domain : str
+        Only useful when 'py'.
+
+    info : dict
+        With keys "module" and "fullname".
+
+    edit : bool, default=False
+        Jump right to the edit page.
+
+    Returns
+    -------
+    url : str
+        The code URL.
+
+    Notes
+    -----
+    This has been adapted to deal with our "verbose" decorator.
+
+    Adapted from mne (mne/utils/docs.py), which was adapted from SciPy (doc/source/conf.py).
+    """
+    import ansys.mapdl.core as pymapdl
+
+    if domain != "py":
+        return None
+
+    modname = info["module"]
+    fullname = info["fullname"]
+
+    submod = sys.modules.get(modname)
+    if submod is None:
+        return None
+
+    obj = submod
+    for part in fullname.split("."):
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            pass
+
+    # deal with our decorators properly
+    while hasattr(obj, "fget"):
+        obj = obj.fget
+
+    try:
+        fn = inspect.getsourcefile(obj)
+    except Exception:  # pragma: no cover
+        fn = None
+
+    if not fn:  # pragma: no cover
+        try:
+            fn = inspect.getsourcefile(sys.modules[obj.__module__])
+        except Exception:
+            return None
+        return None
+
+    repo_path = pymapdl.__file__
+    repo_path = repo_path[: repo_path.index("src")]
+    fn = fn.replace(repo_path, "")
+
+    try:
+        source, lineno = inspect.getsourcelines(obj)
+    except Exception:  # pragma: no cover
+        lineno = None
+
+    if lineno and not edit:
+        linespec = f"#L{lineno}-L{lineno + len(source) - 1}"
+    else:
+        linespec = ""
+
+    if "dev" in pymapdl.__version__:
+        kind = "main"
+    else:  # pragma: no cover
+        kind = f"release/{'.'.join(pymapdl.__version__.split('.')[:2])}"
+
+    blob_or_edit = "edit" if edit else "blob"
+
+    return f"http://github.com/pyansys/pymapdl/{blob_or_edit}/{kind}/{fn}{linespec}"