Merge pull request #204 from daizutabi/buttons

Change anchors

src/mkapi/page.py

@@ -27,7 +27,6 @@ class PageKind(Enum):
 
 
 URIS: dict[str, dict[str, str]] = {}
-ANCHORS = {"object": "docs", "source": "source"}
 
 
 @dataclass
@@ -154,9 +153,17 @@ def _render(
     return mkapi.renderer.render(name, module, level, namespace, predicate)
 
 
-# Link for [source] or [docs]
 OBJECT_LINK_PATTERN = re.compile(r"^__mkapi__\.__(.+)__\.(.+)$")
-DEFINITION_LINK_TEXT = "mkapi_definition_mkapi"
+ANCHOR_PLACEHOLDERS = {
+    "object": "mkapi_object_mkapi",
+    "source": "mkapi_source_mkapi",
+    "definition": "mkapi_definition_mkapi",
+}
+ANCHOR_TITLES = {
+    "object": "Go to docs",
+    "source": "Go to source",
+    "definition": "Go to definition",
+}
 
 
 def _link(match: re.Match, src_uri: str, namespace: str) -> str:
@@ -172,11 +179,11 @@ def _link(match: re.Match, src_uri: str, namespace: str) -> str:
         namespace, fullname = m.groups()
 
         if namespace == "definition" and "object" in URIS:
-            name = DEFINITION_LINK_TEXT
+            name = ANCHOR_PLACEHOLDERS["definition"]
             namespace = "object"
 
-        elif namespace in ANCHORS and namespace in URIS:
-            name = f"[{ANCHORS[namespace]}]"
+        elif namespace in ANCHOR_PLACEHOLDERS and namespace in URIS:
+            name = ANCHOR_PLACEHOLDERS[namespace]
         else:
             return ""
 
@@ -192,10 +199,10 @@ def _link(match: re.Match, src_uri: str, namespace: str) -> str:
     if uri := URIS[namespace].get(fullname):
         uri = os.path.relpath(uri, PurePath(src_uri).parent)
         uri = uri.replace("\\", "/")  # Normalize for Windows
-        title = "Go to definition" if name == DEFINITION_LINK_TEXT else fullname
+        title = ANCHOR_TITLES[namespace]
         return f'[{name}]({uri}#{fullname} "{title}")'
 
-    if from_mkapi and name != DEFINITION_LINK_TEXT:
+    if from_mkapi and name != ANCHOR_PLACEHOLDERS["definition"]:
         return f'<span class="mkapi-tooltip" title="{fullname}">{name}</span>'
 
     return asname
@@ -204,19 +211,26 @@ def _link(match: re.Match, src_uri: str, namespace: str) -> str:
 SOURCE_LINK_PATTERN = re.compile(r"(<span[^<]+?)## __mkapi__\.(\S+?)(</span>)")
 HEADING_PATTERN = re.compile(r"<h(\d).+?mkapi-heading.+?>(.+?)</h\d>\n?")
 
+ANCHOR_TEXTS = {
+    "object": "docs",
+    "source": "source",
+    "definition": '<i class="fa-solid fa-square-arrow-up-right"></i>',
+}
+
 
 def convert_html(html: str, src_uri: str, namespace: str) -> str:
     """Convert HTML for source pages."""
-    def_icon = '<i class="fa-solid fa-square-arrow-up-right"></i>'
-    html = html.replace(DEFINITION_LINK_TEXT, def_icon)
+    for name, anchor in ANCHOR_TEXTS.items():
+        html = html.replace(ANCHOR_PLACEHOLDERS[name], anchor)
+
     link = partial(_link_source, src_uri=src_uri, namespace=namespace)
     html = SOURCE_LINK_PATTERN.sub(link, html)
 
     return HEADING_PATTERN.sub(_heading, html)
 
 
 def _link_source(match: re.Match, src_uri: str, namespace: str) -> str:
-    anchor = ANCHORS[namespace]
+    anchor = ANCHOR_TEXTS[namespace]
     open_tag, name, close_tag = match.groups()
 
     if uri := URIS[namespace].get(name):
@@ -225,7 +239,8 @@ def _link_source(match: re.Match, src_uri: str, namespace: str) -> str:
         uri = uri.replace("/README", "")  # Remove `/README`
 
         href = f"{uri}/#{name}"
-        link = f'<a href="{href}">[{anchor}]</a>'
+        title = ANCHOR_TITLES[namespace]
+        link = f'<a href="{href}" title="{title}">{anchor}</a>'
         # https://github.com/daizutabi/mkapi/issues/123: <span> -> <div>
         link = f'<div class="mkapi-source-link" id="{name}">{link}</div>'
     else:

src/mkapi/templates/document.jinja2

@@ -1,6 +1,4 @@
 <div class="mkapi-document" markdown="1">
-{{ doc.text|safe }}
-
 {%- if bases -%}
 <p class="mkapi-bases" markdown="1">Bases :
 {% for base in bases %}<span class="mkapi-base">{{ base|safe }}</span>
@@ -9,6 +7,8 @@
 </p>
 {%- endif %}
 
+{{ doc.text|safe }}
+
 {% for section in doc.sections -%}
 {% if section.name and not section.kind -%}
 <p class="mkapi-section">

tests/test_page.py

@@ -134,57 +134,57 @@ def test_link():
     m = LINK_PATTERN.match("[A][__mkapi__.__source__.b.c]")
     assert m
     m = _link(m, "y/a.md", "N")
-    assert m == '[[source]](B.md#b.c "b.c")'
+    assert m == '[mkapi_source_mkapi](B.md#b.c "Go to source")'
 
 
 def test_link_not_from_mkapi():
     from mkapi.page import LINK_PATTERN, URIS, _link
 
-    URIS["N"] = {"x.y": "z/a/c.md"}
+    URIS["definition"] = {"x.y": "z/a/c.md"}
     m = LINK_PATTERN.match("[A][x.y]")
     assert m
-    m = _link(m, "y/a.md", "N")
-    assert m == '[A](../z/a/c.md#x.y "x.y")'
+    m = _link(m, "y/a.md", "definition")
+    assert m == '[A](../z/a/c.md#x.y "Go to definition")'
 
 
 def test_link_not_from_mkapi_invalid():
     from mkapi.page import LINK_PATTERN, URIS, _link
 
-    URIS["N"] = {}
+    URIS["object"] = {}
     m = LINK_PATTERN.match("[A][x.y]")
     assert m
-    m = _link(m, "y/a.md", "N")
+    m = _link(m, "y/a.md", "object")
     assert m == "[A][x.y]"
 
 
 def test_link_backticks():
     from mkapi.page import LINK_PATTERN, URIS, _link
 
-    URIS["N"] = {"x.y": "p/B.md"}
+    URIS["source"] = {"x.y": "p/B.md"}
     m = LINK_PATTERN.match("[`A`][x.y]")
     assert m
-    m = _link(m, "q/r/a.md", "N")
-    assert m == '[`A`](../../p/B.md#x.y "x.y")'
+    m = _link(m, "q/r/a.md", "source")
+    assert m == '[`A`](../../p/B.md#x.y "Go to source")'
 
 
 def test_link_without_fullname():
     from mkapi.page import LINK_PATTERN, URIS, _link
 
-    URIS["N"] = {"x.y": "q/r/a.md"}
+    URIS["object"] = {"x.y": "q/r/a.md"}
     m = LINK_PATTERN.match("[x.y][]")
     assert m
-    m = _link(m, "q/r/a.md", "N")
-    assert m == '[x.y](a.md#x.y "x.y")'
+    m = _link(m, "q/r/a.md", "object")
+    assert m == '[x.y](a.md#x.y "Go to docs")'
 
 
 def test_link_without_fullname_backticks():
     from mkapi.page import LINK_PATTERN, URIS, _link
 
-    URIS["N"] = {"x.y": "q/s/a.md"}
+    URIS["source"] = {"x.y": "q/s/a.md"}
     m = LINK_PATTERN.match("[`x.y`][]")
     assert m
-    m = _link(m, "q/r/a.md", "N")
-    assert m == '[`x.y`](../s/a.md#x.y "x.y")'
+    m = _link(m, "q/r/a.md", "source")
+    assert m == '[`x.y`](../s/a.md#x.y "Go to source")'
 
 
 def test_page_convert_object_page():