From ddc09906492c60267766098e1423ee8e657a914c Mon Sep 17 00:00:00 2001
From: Michael Wang <isVoid@users.noreply.github.com>
Date: Mon, 8 Mar 2021 12:05:05 -0800
Subject: [PATCH] Resolving unlinked type shorthands in cudf doc (#7416)

Closes #7320

This PR adds an additional preprocessing step in documentation generation. It traverses through the doctree generated by Sphinx and replaces unresolved type short hands with proper target reference, while keeping the shortened name for display text.

An additional preprocessing step is added to ignore internal types to APIs facing both internally and externally, such as `cudf.core.column.string.StringColumn`

`cupy` API reference is added to intersphinx.

Minor changes:
- Fixes a small doc bug in `frame.copy`

Authors:
  - Michael Wang (@isVoid)

Approvers:
  - Ashwin Srinath (@shwina)

URL: https://github.com/rapidsai/cudf/pull/7416
---
 docs/cudf/source/conf.py               | 59 ++++++++++++++++++++++----
 python/cudf/cudf/core/column/string.py |  2 +-
 2 files changed, 52 insertions(+), 9 deletions(-)

diff --git a/docs/cudf/source/conf.py b/docs/cudf/source/conf.py
index 54866ff6eee..b68d7b5849f 100644
--- a/docs/cudf/source/conf.py
+++ b/docs/cudf/source/conf.py
@@ -21,7 +21,10 @@
 #
 import os
 import sys
+
+from docutils.nodes import Text
 from recommonmark.transform import AutoStructify
+from sphinx.addnodes import pending_xref
 
 sys.path.insert(0, os.path.abspath("../.."))
 
@@ -74,9 +77,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.19'
+version = "0.19"
 # The full version, including alpha/beta/rc tags.
-release = '0.19.0'
+release = "0.19.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -193,7 +196,10 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/": None}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/", None),
+    "cupy": ("https://docs.cupy.dev/en/stable/", None),
+}
 
 # Config numpydoc
 numpydoc_show_inherited_class_members = True
@@ -202,14 +208,51 @@
 autoclass_content = "init"
 
 # Config AutoStructify
-github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
+github_doc_root = "https://github.com/rtfd/recommonmark/tree/master/doc/"
+
+# Replace API shorthands with fullname
+_reftarget_aliases = {
+    "cudf.Series": ("cudf.core.series.Series", "cudf.Series"),
+    "cudf.Index": ("cudf.core.index.Index", "cudf.Index"),
+    "cupy.core.core.ndarray": ("cupy.ndarray", "cupy.ndarray"),
+}
+
+_internal_names_to_ignore = {"cudf.core.column.string.StringColumn"}
+
+
+def resolve_aliases(app, doctree):
+    pending_xrefs = doctree.traverse(condition=pending_xref)
+    for node in pending_xrefs:
+        alias = node.get("reftarget", None)
+        if alias is not None and alias in _reftarget_aliases:
+            real_ref, text_to_render = _reftarget_aliases[alias]
+            node["reftarget"] = real_ref
+
+            text_node = next(
+                iter(node.traverse(lambda n: n.tagname == "#text"))
+            )
+            text_node.parent.replace(text_node, Text(text_to_render, ""))
+
+
+def ignore_internal_references(app, env, node, contnode):
+    name = node.get("reftarget", None)
+    if name is not None and name in _internal_names_to_ignore:
+        node["reftarget"] = ""
+        return contnode
+
 
 def setup(app):
     app.add_js_file("copybutton_pydocs.js")
     app.add_css_file("params.css")
     app.add_css_file("https://docs.rapids.ai/assets/css/custom.css")
-    app.add_config_value('recommonmark_config', {
-            'url_resolver': lambda url: github_doc_root + url,
-            'auto_toc_tree_section': 'Contents',
-            }, True)
+    app.add_config_value(
+        "recommonmark_config",
+        {
+            "url_resolver": lambda url: github_doc_root + url,
+            "auto_toc_tree_section": "Contents",
+        },
+        True,
+    )
     app.add_transform(AutoStructify)
+    app.connect("doctree-read", resolve_aliases)
+    app.connect("missing-reference", ignore_internal_references)
diff --git a/python/cudf/cudf/core/column/string.py b/python/cudf/cudf/core/column/string.py
index 0a1f6529cc7..81abdd3f66a 100644
--- a/python/cudf/cudf/core/column/string.py
+++ b/python/cudf/cudf/core/column/string.py
@@ -347,7 +347,7 @@ def cat(self, sep: str = None, na_rep: str = None) -> str:
     @overload
     def cat(
         self, others, sep: str = None, na_rep: str = None
-    ) -> Union[ParentType, "cudf.core.column.StringColumn"]:
+    ) -> Union[ParentType, "cudf.core.column.string.StringColumn"]:
         ...
 
     def cat(self, others=None, sep=None, na_rep=None):