feat(gui): links to other declarations in documentation (#797)

* feat(gui): resolve relative links to functions in documentation

* feat(gui): resolve relative links to classes in documentation

* feat(gui): underline links in documentation

* feat(gui): replace links to modules

* feat(gui): always display preferred qualified name

Author: lars-reimann

api-editor/gui/src/features/menuBar/SelectionBreadcrumbs.tsx

@@ -18,7 +18,7 @@ export const SelectionBreadcrumbs = function () {
     return (
         <Breadcrumb>
             {declarations.map((it) => (
-                <BreadcrumbItem>
+                <BreadcrumbItem key={it.id}>
                     <RouterLink to={it.id}>{it.name}</RouterLink>
                 </BreadcrumbItem>
             ))}

api-editor/gui/src/features/packageData/model/PythonDeclaration.ts

@@ -15,6 +15,17 @@ export abstract class PythonDeclaration {
         return this.name;
     }
 
+    root(): PythonDeclaration {
+        let current: PythonDeclaration = this;
+        while (true) {
+            const parent = current.parent();
+            if (!parent) {
+                return current;
+            }
+            current = parent;
+        }
+    }
+
     *ancestorsOrSelf(): Generator<PythonDeclaration> {
         let current: Optional<PythonDeclaration> = this;
         while (current) {

api-editor/gui/src/features/packageData/selectionView/ClassView.tsx

@@ -33,7 +33,7 @@ export const ClassView: React.FC<ClassViewProps> = function ({ pythonClass }) {
 
                 <Box paddingLeft={4}>
                     {pythonClass.description ? (
-                        <DocumentationText inputText={pythonClass.description} />
+                        <DocumentationText declaration={pythonClass} inputText={pythonClass.description} />
                     ) : (
                         <ChakraText color="gray.500">There is no documentation for this class.</ChakraText>
                     )}

api-editor/gui/src/features/packageData/selectionView/DocumentationText.tsx

@@ -1,42 +1,72 @@
-import { Code, Flex, HStack, IconButton, Stack, Text as ChakraText, UnorderedList } from '@chakra-ui/react';
+import {
+    Code,
+    Flex,
+    HStack,
+    IconButton,
+    Link as ChakraLink,
+    Stack,
+    Text as ChakraText,
+    UnorderedList,
+} from '@chakra-ui/react';
 import 'katex/dist/katex.min.css';
 import React, { ClassAttributes, FunctionComponent, HTMLAttributes, useState } from 'react';
 import { FaChevronDown, FaChevronRight } from 'react-icons/fa';
 import ReactMarkdown from 'react-markdown';
-import { CodeComponent, ReactMarkdownProps, UnorderedListComponent } from 'react-markdown/lib/ast-to-react';
+import {
+    CodeComponent,
+    ComponentPropsWithoutRef,
+    ComponentType,
+    ReactMarkdownProps,
+    UnorderedListComponent,
+} from 'react-markdown/lib/ast-to-react';
 import rehypeKatex from 'rehype-katex';
 import remarkGfm from 'remark-gfm';
 import remarkMath from 'remark-math';
 import { useAppSelector } from '../../../app/hooks';
 import { selectExpandDocumentationByDefault } from '../../ui/uiSlice';
+import { Link as RouterLink } from 'react-router-dom';
+import { PythonDeclaration } from '../model/PythonDeclaration';
+import { PythonPackage } from '../model/PythonPackage';
 
 interface DocumentationTextProps {
+    declaration: PythonDeclaration;
     inputText: string;
 }
 
 type ParagraphComponent = FunctionComponent<
     ClassAttributes<HTMLParagraphElement> & HTMLAttributes<HTMLParagraphElement> & ReactMarkdownProps
 >;
 
-const CustomText: ParagraphComponent = function ({ className, children }) {
-    return <ChakraText className={className}>{children}</ChakraText>;
+type LinkComponent = ComponentType<ComponentPropsWithoutRef<'a'> & ReactMarkdownProps>;
+
+const CustomLink: LinkComponent = function ({ className, children, href }) {
+    return (
+        <ChakraLink as={RouterLink} to={href ?? '#'} className={className} textDecoration="underline">
+            {children}
+        </ChakraLink>
+    );
 };
 
 const CustomCode: CodeComponent = function ({ className, children }) {
     return <Code className={className}>{children}</Code>;
 };
 
+const CustomText: ParagraphComponent = function ({ className, children }) {
+    return <ChakraText className={className}>{children}</ChakraText>;
+};
+
 const CustomUnorderedList: UnorderedListComponent = function ({ className, children }) {
     return <UnorderedList className={className}>{children}</UnorderedList>;
 };
 
 const components = {
-    p: CustomText,
+    a: CustomLink,
     code: CustomCode,
+    p: CustomText,
     ul: CustomUnorderedList,
 };
 
-export const DocumentationText: React.FC<DocumentationTextProps> = function ({ inputText = '' }) {
+export const DocumentationText: React.FC<DocumentationTextProps> = function ({ declaration, inputText = '' }) {
     const expandDocumentationByDefault = useAppSelector(selectExpandDocumentationByDefault);
 
     const preprocessedText = inputText
@@ -45,7 +75,21 @@ export const DocumentationText: React.FC<DocumentationTextProps> = function ({ i
         // replace inline math elements
         .replaceAll(/:math:`([^`]*)`/gu, '$$1$')
         // replace block math elements
-        .replaceAll(/\.\. math::\s*(\S.*)\n\n/gu, '$$\n$1\n$$\n\n');
+        .replaceAll(/\.\. math::\s*(\S.*)\n\n/gu, '$$\n$1\n$$\n\n')
+        // replace relative links to classes
+        .replaceAll(/:class:`(\w*)`/gu, (_match, name) => resolveRelativeLink(declaration, name))
+        // replace relative links to functions
+        .replaceAll(/:func:`(\w*)`/gu, (_match, name) => resolveRelativeLink(declaration, name))
+        // replace absolute links to modules
+        .replaceAll(/:mod:`([\w.]*)`/gu, (_match, qualifiedName) => resolveAbsoluteLink(declaration, qualifiedName, 1))
+        // replace absolute links to classes
+        .replaceAll(/:class:`~?([\w.]*)`/gu, (_match, qualifiedName) =>
+            resolveAbsoluteLink(declaration, qualifiedName, 2),
+        )
+        // replace absolute links to classes
+        .replaceAll(/:func:`~?([\w.]*)`/gu, (_match, qualifiedName) =>
+            resolveAbsoluteLink(declaration, qualifiedName, 2),
+        );
 
     const shortenedText = preprocessedText.split('\n\n')[0];
     const hasMultipleLines = shortenedText !== preprocessedText;
@@ -91,3 +135,49 @@ export const DocumentationText: React.FC<DocumentationTextProps> = function ({ i
         </Flex>
     );
 };
+
+const resolveRelativeLink = function (currentDeclaration: PythonDeclaration, linkedDeclarationName: string): string {
+    const parent = currentDeclaration.parent();
+    if (!parent) {
+        return linkedDeclarationName;
+    }
+
+    const sibling = parent.children().find((it) => it.name === linkedDeclarationName);
+    if (!sibling) {
+        return linkedDeclarationName;
+    }
+
+    return `[${currentDeclaration.preferredQualifiedName()}](${sibling.id})`;
+};
+
+const resolveAbsoluteLink = function (
+    currentDeclaration: PythonDeclaration,
+    linkedDeclarationQualifiedName: string,
+    segmentCount: number,
+): string {
+    let segments = linkedDeclarationQualifiedName.split('.');
+    if (segments.length < segmentCount) {
+        return linkedDeclarationQualifiedName;
+    }
+
+    segments = [
+        segments.slice(0, segments.length - segmentCount + 1).join('.'),
+        ...segments.slice(segments.length - segmentCount + 1),
+    ];
+
+    let current = currentDeclaration.root();
+    if (!(current instanceof PythonPackage)) {
+        return linkedDeclarationQualifiedName;
+    }
+
+    for (const segment of segments) {
+        const next = current.children().find((it) => it.name === segment);
+        if (!next) {
+            return linkedDeclarationQualifiedName;
+        }
+
+        current = next;
+    }
+
+    return `[${current.preferredQualifiedName()}](${current.id})`;
+};

api-editor/gui/src/features/packageData/selectionView/FunctionView.tsx

@@ -57,7 +57,7 @@ export const FunctionView: React.FC<FunctionViewProps> = function ({ pythonFunct
 
                 <Box paddingLeft={4}>
                     {pythonFunction.description ? (
-                        <DocumentationText inputText={pythonFunction.description} />
+                        <DocumentationText declaration={pythonFunction} inputText={pythonFunction.description} />
                     ) : (
                         <ChakraText color="gray.500">There is no documentation for this function.</ChakraText>
                     )}

api-editor/gui/src/features/packageData/selectionView/ParameterNode.tsx

@@ -55,7 +55,7 @@ export const ParameterNode: React.FC<ParameterNodeProps> = function ({ isTitle,
 
             <Box paddingLeft={4}>
                 {pythonParameter.description ? (
-                    <DocumentationText inputText={pythonParameter?.description} />
+                    <DocumentationText declaration={pythonParameter} inputText={pythonParameter?.description} />
                 ) : (
                     <ChakraText color="gray.500">There is no documentation for this parameter.</ChakraText>
                 )}