From 299abc8006b268b97f119545a7d180821e758dcd Mon Sep 17 00:00:00 2001
From: Tim Pechersky <tim.pechersky@gmail.com>
Date: Mon, 30 Sep 2024 18:52:20 +0700
Subject: [PATCH 1/2] update doc template

---
 docs/templates/common.hbs   |  3 ++-
 docs/templates/contract.hbs |  5 +----
 docs/templates/helpers.ts   | 16 +++++++++++++---
 3 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/templates/common.hbs b/docs/templates/common.hbs
index 40fa2a9..d6e0aa9 100644
--- a/docs/templates/common.hbs
+++ b/docs/templates/common.hbs
@@ -1,4 +1,3 @@
-{{h 2}} {{visibility}} {{toLowerCase type}} {{name}}
 
 {{#if (isVisible visibility)}}
 {{h 2}}  {{name}}
@@ -10,6 +9,7 @@
 {{{signature}}}
 ```
 {{/if}}
+{{/if}}
 
 {{#if natspec.params}}
 | Input | Type | Description |
@@ -36,3 +36,4 @@
 {{#if natspec.dev}}
 {{{transformDev (substituteAnchors natspec.dev)}}}
 {{/if}}
+
diff --git a/docs/templates/contract.hbs b/docs/templates/contract.hbs
index e1c0bff..eb3beae 100644
--- a/docs/templates/contract.hbs
+++ b/docs/templates/contract.hbs
@@ -1,10 +1,7 @@
-## Description
-
 {{{natspec.notice}}}
 
-{{{natspec.dev}}}
+{{{transformDev (substituteAnchors natspec.dev)}}}
 
-## Implementation
 
 {{#each items}}
 {{>item}}
diff --git a/docs/templates/helpers.ts b/docs/templates/helpers.ts
index ce013d4..ac958ae 100644
--- a/docs/templates/helpers.ts
+++ b/docs/templates/helpers.ts
@@ -64,7 +64,7 @@ export function joinLines(text?: string) {
 
 export function transformDev(comment: string): string {
   // Split the comment into lines
-  const lines = comment.split('\n');
+  const lines = comment?.split('\n') ?? [];
 
   // Initialize variables to store the transformed text
   let transformedText = '';
@@ -117,8 +117,18 @@ export const isVisible = (type: string) => {
 
 export const substituteAnchors = (text: string) => {
   if (typeof text === 'string') {
-    return text.replace(/{(\w+)}/g, (match: string, p1: string) => {
-      return `[${p1}](#${p1.toLocaleLowerCase()})`;
+    return text.replace(/{([^}]+)}/g, (match: string, p1: string) => {
+      // Split the reference into parts
+      const parts = p1.split('.');
+      const anchor = parts.length > 1 ? `#${parts.slice(1).join('.').toLocaleLowerCase()}` : '';
+      const reference = parts[0];
+      const displayText = reference.charAt(0).toUpperCase() + reference.slice(1);
+
+      // Handle different depth levels
+      const path = reference.startsWith('../') ? reference : `./${reference}`;
+
+      return `[${displayText}${anchor}](../${path}${anchor})`;
     });
   }
+  return text;
 };

From 0ddfde989e4c1bd04c8667c133579051f21a93aa Mon Sep 17 00:00:00 2001
From: Tim Pechersky <tim.pechersky@gmail.com>
Date: Mon, 30 Sep 2024 18:52:20 +0700
Subject: [PATCH 2/2] update doc template

---
 .changeset/selfish-cars-study.md |  5 +++++
 docs/templates/common.hbs        |  3 ++-
 docs/templates/contract.hbs      |  5 +----
 docs/templates/helpers.ts        | 16 +++++++++++++---
 4 files changed, 21 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/selfish-cars-study.md

diff --git a/.changeset/selfish-cars-study.md b/.changeset/selfish-cars-study.md
new file mode 100644
index 0000000..4de9bf2
--- /dev/null
+++ b/.changeset/selfish-cars-study.md
@@ -0,0 +1,5 @@
+---
+'rankify-contracts': patch
+---
+
+doc generation template improvements
diff --git a/docs/templates/common.hbs b/docs/templates/common.hbs
index 40fa2a9..d6e0aa9 100644
--- a/docs/templates/common.hbs
+++ b/docs/templates/common.hbs
@@ -1,4 +1,3 @@
-{{h 2}} {{visibility}} {{toLowerCase type}} {{name}}
 
 {{#if (isVisible visibility)}}
 {{h 2}}  {{name}}
@@ -10,6 +9,7 @@
 {{{signature}}}
 ```
 {{/if}}
+{{/if}}
 
 {{#if natspec.params}}
 | Input | Type | Description |
@@ -36,3 +36,4 @@
 {{#if natspec.dev}}
 {{{transformDev (substituteAnchors natspec.dev)}}}
 {{/if}}
+
diff --git a/docs/templates/contract.hbs b/docs/templates/contract.hbs
index e1c0bff..eb3beae 100644
--- a/docs/templates/contract.hbs
+++ b/docs/templates/contract.hbs
@@ -1,10 +1,7 @@
-## Description
-
 {{{natspec.notice}}}
 
-{{{natspec.dev}}}
+{{{transformDev (substituteAnchors natspec.dev)}}}
 
-## Implementation
 
 {{#each items}}
 {{>item}}
diff --git a/docs/templates/helpers.ts b/docs/templates/helpers.ts
index ce013d4..ac958ae 100644
--- a/docs/templates/helpers.ts
+++ b/docs/templates/helpers.ts
@@ -64,7 +64,7 @@ export function joinLines(text?: string) {
 
 export function transformDev(comment: string): string {
   // Split the comment into lines
-  const lines = comment.split('\n');
+  const lines = comment?.split('\n') ?? [];
 
   // Initialize variables to store the transformed text
   let transformedText = '';
@@ -117,8 +117,18 @@ export const isVisible = (type: string) => {
 
 export const substituteAnchors = (text: string) => {
   if (typeof text === 'string') {
-    return text.replace(/{(\w+)}/g, (match: string, p1: string) => {
-      return `[${p1}](#${p1.toLocaleLowerCase()})`;
+    return text.replace(/{([^}]+)}/g, (match: string, p1: string) => {
+      // Split the reference into parts
+      const parts = p1.split('.');
+      const anchor = parts.length > 1 ? `#${parts.slice(1).join('.').toLocaleLowerCase()}` : '';
+      const reference = parts[0];
+      const displayText = reference.charAt(0).toUpperCase() + reference.slice(1);
+
+      // Handle different depth levels
+      const path = reference.startsWith('../') ? reference : `./${reference}`;
+
+      return `[${displayText}${anchor}](../${path}${anchor})`;
     });
   }
+  return text;
 };