docs: create reference documentation with beautifully styled (#57)

* wip

* renew reference docs

* fix

* fix

* works

Author: seokju-na

.github/CONTRIBUTING.md

@@ -75,3 +75,25 @@ feat(repository): add options for initialize repository
 docs: fix link to website page
 chore: upgrade vitest to v3
 ```
+
+## Documentation
+
+This project aims to maintain high documentation quality.
+
+Please refer to the following guide to create robust references using JSDoc.
+
+- `@category` : Specifies the category in which the reference documentation will be placed. You can use `/` to specify depth (e.g. `Repository/Methods`).
+- `@signature` : Describes what type of signature a function or method has. Please write a type declaration in the TypeScript language.
+- `@param` : Write all parameters.
+- `@returns` : Specifies what value is returned.
+- `@throws` : Write documentation for errors that should be noted.
+- `@example` : Examples are not required, but are recommended as they make the behavior easier to understand.
+
+To automatically generate reference documentation after writing a JSDoc, please run the command below.
+
+```shell
+yarn build
+
+cd docs/
+yarn gen-reference
+```

README-ko_kr.md

@@ -24,7 +24,7 @@ console.log(head); // "refs/heads/main"
 ## 문서
 
 - [사용법](https://es-git.slash.page/ko/usage/repository.html)
-- [레퍼런스](https://es-git.slash.page/ko/reference/globals.html)
+- [레퍼런스](https://es-git.slash.page/ko/reference/Repository/openRepository.html)
 
 ## 기여하기
 

README.md

@@ -24,7 +24,7 @@ console.log(head); // "refs/heads/main"
 ## Documentation
 
 - [Usage](https://es-git.slash.page/usage/repository.html)
-- [Reference](https://es-git.slash.page/reference/globals.html)
+- [Reference](https://es-git.slash.page/reference/Repository/openRepository.html)
 
 ## Contributing
 

docs/.gitignore

@@ -1,2 +1,3 @@
 .vitepress/cache
 typedoc-generated/
+typedoc-generated.json

docs/.vitepress/en.ts

@@ -26,28 +26,33 @@ function nav(): DefaultTheme.NavItem[] {
     { text: 'Home', link: '/' },
     { text: 'Getting Started', link: '/getting-started' },
     { text: 'Usage', link: '/usage/repository' },
+    { text: 'Reference', link: '/reference/Repository/openRepository' },
   ];
 }
 
 function sidebar(): DefaultTheme.Sidebar {
   return [
     {
-      text: 'Getting Started',
-      link: '/getting-started',
-    },
-    {
-      text: 'Usage',
+      text: 'Guides',
       items: [
-        { text: 'Repository', link: '/usage/repository' },
-        { text: 'Remotes', link: '/usage/remote' },
-        { text: 'Commit History', link: '/usage/history' },
-        { text: 'Commit Changes', link: '/usage/commit' },
-        { text: 'Tags', link: '/usage/tag' },
+        {
+          text: 'Getting Started',
+          link: '/getting-started',
+        },
+        {
+          text: 'Usage',
+          items: [
+            { text: 'Repository', link: '/usage/repository' },
+            { text: 'Remotes', link: '/usage/remote' },
+            { text: 'Commit History', link: '/usage/history' },
+            { text: 'Commit Changes', link: '/usage/commit' },
+            { text: 'Tags', link: '/usage/tag' },
+          ],
+        },
       ],
     },
     {
       text: 'Reference',
-      link: '/reference/globals',
       items: getReferenceSidebarItems(docsRoot),
     },
   ];

docs/.vitepress/ko.ts

@@ -26,28 +26,33 @@ function nav(): DefaultTheme.NavItem[] {
     { text: '홈', link: '/ko' },
     { text: '시작하기', link: '/ko/getting-started' },
     { text: '사용법', link: '/ko/usage/repository' },
+    { text: '레퍼런스', link: '/ko/reference/Repository/openRepository' },
   ];
 }
 
 function sidebar(): DefaultTheme.Sidebar {
   return [
     {
-      text: '시작하기',
-      link: '/ko/getting-started',
-    },
-    {
-      text: '사용법',
+      text: '가이드',
       items: [
-        { text: '리포지토리', link: '/ko/usage/repository' },
-        { text: '리모트', link: '/ko/usage/remote' },
-        { text: '커밋 히스토리', link: '/ko/usage/history' },
-        { text: '커밋하기', link: '/ko/usage/commit' },
-        { text: '태그', link: '/ko/usage/tag' },
+        {
+          text: '시작하기',
+          link: '/ko/getting-started',
+        },
+        {
+          text: '사용법',
+          items: [
+            { text: '리포지토리', link: '/ko/usage/repository' },
+            { text: '리모트', link: '/ko/usage/remote' },
+            { text: '커밋 히스토리', link: '/ko/usage/history' },
+            { text: '커밋하기', link: '/ko/usage/commit' },
+            { text: '태그', link: '/ko/usage/tag' },
+          ],
+        },
       ],
     },
     {
       text: '레퍼런스',
-      link: '/ko/reference/globals',
       items: getReferenceSidebarItems(docsRoot, 'ko'),
     },
   ];

docs/.vitepress/lib/sidebar.ts

@@ -1,12 +1,62 @@
-import fs from 'node:fs';
 import path from 'node:path';
+import glob from 'fast-glob';
 import type { DefaultTheme } from 'vitepress';
 
 export function getReferenceSidebarItems(docsRoot: string, lang?: string) {
-  const jsonFilepath =
-    lang != null
-      ? path.join(docsRoot, lang, 'reference', 'typedoc-sidebar.json')
-      : path.join(docsRoot, 'reference', 'typedoc-sidebar.json');
-  const json = fs.readFileSync(jsonFilepath, 'utf8');
-  return JSON.parse(json) as DefaultTheme.SidebarItem[];
+  const files = glob.sync('**/*.md', {
+    cwd: lang != null ? path.join(docsRoot, lang, 'reference') : path.join(docsRoot, 'reference'),
+    onlyFiles: true,
+  });
+  files.sort((a, b) => {
+    const aName = path.basename(a, '.md');
+    const bName = path.basename(b, '.md');
+    if (aName < bName) {
+      return -1;
+    }
+    if (aName > bName) {
+      return 1;
+    }
+    return 0;
+  });
+
+  const items: DefaultTheme.SidebarItem[] = [];
+  for (const file of files) {
+    const parts = file.split('/');
+    const link = lang != null ? `/${lang}/reference/${file}` : `/reference/${file}`;
+    let current = items;
+    if (parts.length > 1) {
+      for (const part of parts.slice(0, parts.length - 1)) {
+        let node = current.find(x => x.text === part);
+        if (node == null) {
+          node = { text: part, items: [], collapsed: true };
+          current.push(node);
+        }
+        current = node.items!;
+      }
+    }
+    current.push({
+      text: path.basename(file, '.md'),
+      link: link.replace(path.extname(link), ''),
+    });
+  }
+  sortItems(items);
+  return items;
+}
+
+function sortItems(items: DefaultTheme.SidebarItem[]) {
+  items.sort((a, b) => {
+    const textDiff = a.text! < b.text! ? -1 : a.text! < b.text! ? 1 : 0;
+    if (a.link != null && b.link == null) {
+      return 1;
+    }
+    if (a.link == null && b.link != null) {
+      return -1;
+    }
+    return textDiff;
+  });
+  for (const item of items) {
+    if (item.items != null) {
+      sortItems(item.items);
+    }
+  }
 }

docs/.vitepress/theme/index.css

@@ -1,4 +1,6 @@
 :root {
+  --vp-c-brand-1: rgb(27, 109, 225);
+  --vp-c-brand-2: rgb(55, 113, 212);
   --vp-nav-logo-height: 16px;
   --vp-font-family-base: "Toss Product Sans", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
     "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
@@ -7,3 +9,62 @@
 :root[lang="ko"] {
   word-break: keep-all;
 }
+
+ul.param-ul {
+  margin-top: 8px;
+  padding: 0;
+  list-style: none;
+
+  & > li.param-li {
+    position: relative;
+    padding-left: 16px;
+    margin-left: 12px;
+    margin-top: 0;
+    margin-bottom: 12px;
+  }
+
+  & > li.param-li-root {
+    margin-left: 0;
+    padding-left: 0;
+  }
+
+  & li.param-li::before {
+    position: absolute;
+    left: 0;
+    display: block;
+    content: "";
+    top: 6px;
+    width: 8px;
+    height: 8px;
+    border-left: 2px solid #5c6064;
+    border-bottom: 2px solid #5c6064;
+  }
+
+  & li.param-li-root::before {
+    display: none;
+  }
+}
+
+span.param-name {
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--vp-c-text-1);
+  margin-right: 6px;
+  font-family: Menlo, Consolas, Monaco, "Andale Mono", "Ubuntu Mono", monospace;
+}
+
+span.param-required {
+  font-size: 14px;
+  color: #f5645a;
+}
+
+span.param-type {
+  font-size: 14px;
+  color: #38cc8e;
+}
+
+p.param-description {
+  font-size: 14px;
+  color: var(--vp-c-text-1);
+  margin: 0;
+}