feat: add TSDoc (#6)

Author: giladgd

.config/typedoc.css

@@ -0,0 +1,212 @@
+.tsd-typography h4,
+.tsd-typography .tsd-index-panel h3,
+.tsd-index-panel .tsd-typography h3,
+.tsd-typography h5,
+.tsd-typography h6 {
+    margin: 1.2em 0 0.4em 0;
+}
+
+code {
+    padding: 4px 6px;
+    border-radius: 4px;
+}
+
+pre {
+    border-radius: 4px;
+    padding: 8px 12px;
+    border: none;
+    overflow-x: auto;
+}
+
+.tsd-page-toolbar {
+    border-bottom: none;
+    background: color-mix(in srgb, var(--color-background-secondary), transparent 20%);
+    box-shadow: 0px -148px 86px 86px #000000;
+}
+
+.tsd-page-toolbar .tsd-toolbar-contents {
+    padding: 8px 2rem;
+}
+
+.tsd-page-toolbar:before {
+    width: 100%;
+    position: absolute;
+    content: "";
+    height: 100%;
+    z-index: -1;
+    backdrop-filter: blur(6px);
+}
+
+@media (min-width: 1200px) {
+    .page-menu,
+    .site-menu {
+        top: 82px;
+    }
+}
+
+.tsd-navigation a,
+.tsd-navigation summary > span,
+.tsd-page-navigation a {
+    margin: 4px 0px;
+    padding: 0.25rem 0.55rem 0.25rem 0.3rem;
+    border-radius: 4px;
+}.tsd-navigation a:not(:has(> svg)),
+.tsd-navigation summary > span:not(:has(> svg)),
+.tsd-page-navigation a:not(:has(> svg)) {
+    padding: 0.25rem 0.55rem 0.25rem 0.4rem;
+}
+
+.tsd-navigation a:hover,
+.tsd-navigation summary > span:hover,
+.tsd-page-navigation a:hover {
+    /*opacity: 0.8;*/
+    text-decoration: none;
+    background-color: color-mix(in srgb, currentColor 12%, transparent);
+}
+
+.tsd-navigation a.current,
+.tsd-page-navigation a.current {
+    border-radius: 4px;
+}
+.tsd-navigation a.current:hover,
+.tsd-page-navigation a.current:hover {
+    border-radius: 4px;
+    background-color: color-mix(in srgb, var(--color-active-menu-item), transparent 16%);
+}
+
+pre {
+    position: relative;
+}
+
+pre > button {
+    background-color: color-mix(in srgb, currentColor 12%, transparent);
+    border: none;
+    padding: 6px 12px;
+    border-radius: 4px;
+    cursor: pointer;
+    backdrop-filter: blur(6px);
+    max-height: calc(100% - 8px * 2);
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    box-sizing: border-box;
+    top: 8px;
+    right: 8px;
+}
+pre > button:hover {
+    background-color: color-mix(in srgb, currentColor 18%, transparent);
+}
+
+h3 > svg {
+    vertical-align: middle;
+    margin-inline-end: 6px;
+    transform-origin: 48% 38%;
+}
+
+h5 > svg {
+    vertical-align: middle;
+    margin-inline-end: 6px;
+    transform-origin: 48% 38%;
+}
+
+#tsd-search {
+    border-radius: 4px;
+}
+
+ul.tsd-hierarchy>li {
+    margin: 12px 0px;
+    list-style: disc;
+}
+
+ul.tsd-hierarchy {
+    padding-inline-start: 24px;
+}
+
+code.tsd-tag {
+    border: none;
+    box-shadow: 0px 0px 8px -2px var(--color-accent);
+}
+
+h1 code.tsd-tag:first-of-type {
+    margin-left: 0.55em;
+}
+
+.tsd-page-toolbar a.title:hover {
+    text-decoration: none;
+    background-color: color-mix(in srgb, currentColor 12%, transparent);
+    padding: 4px 8px;
+    margin: -4px -8px;
+    border-radius: 4px;
+}
+
+a.tsd-index-link {
+    padding: 4px !important;
+}
+
+a.tsd-index-link:hover {
+    text-decoration: none;
+    background-color: color-mix(in srgb, currentColor 12%, transparent);
+    border-radius: 8px;
+}
+
+h1:not(.tsd-anchor-link, .tsd-returns-title) > a:hover,
+h2:not(.tsd-anchor-link, .tsd-returns-title) > a:hover,
+h3:not(.tsd-anchor-link, .tsd-returns-title) > a:hover,
+h4:not(.tsd-anchor-link, .tsd-returns-title) > a:hover,
+h5:not(.tsd-anchor-link, .tsd-returns-title) > a:hover,
+h6:not(.tsd-anchor-link, .tsd-returns-title) > a:hover {
+    text-decoration: none;
+    color: var(--color-text);
+}
+
+h1:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before,
+h2:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before,
+h3:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before,
+h4:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before,
+h5:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before,
+h6:not(.tsd-anchor-link, .tsd-returns-title) > a:hover:before {
+    content: "";
+    position: absolute;
+    height: calc(1ex + (1lh - 1ex)/2);
+    margin-top: calc(0.2 * 1ex);
+    margin-left: -8px;
+    width: 3px;
+    background-color: currentColor;
+    border-radius: 9999px;
+    opacity: 0.4;
+    pointer-events: none;
+}
+
+#tsd-search.has-focus {
+    background-color: color-mix(in srgb, var(--color-accent), transparent 60%);
+}
+
+#tsd-search .field input {
+    padding: 12px 16px;
+}
+
+#tsd-search .results li {
+    padding: 0px 16px;
+}
+
+#tsd-search .results li {
+    padding: 0px 16px;
+    background-color: color-mix(in srgb, var(--color-background), transparent 20%);
+}
+
+#tsd-search .results li:nth-child(even) {
+    background-color: color-mix(in srgb, var(--color-background), transparent 20%);
+}
+
+#tsd-search .results li.current,
+#tsd-search .results li:hover {
+    background-color: color-mix(in srgb, var(--color-accent), transparent 20%);
+}
+
+#tsd-search.has-focus .results {
+    backdrop-filter: blur(6px);
+}
+
+.container-main {
+    margin-top: 16px;
+}

.config/typedoc.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "entryPoints": ["../src/index.ts"],
+    "out": "../docs",
+    "tsconfig": "../tsconfig.json",
+    "customCss": "./typedoc.css",
+    "readme": "../README.md",
+    "excludeExternals": true,
+    "excludeInternal": true,
+    "excludePrivate": true,
+    "githubPages": true,
+    "hideGenerator": true,
+    "jsDocCompatibility": true,
+    "htmlLang": "en"
+}

.github/workflows/build.yml

@@ -17,13 +17,20 @@ jobs:
         run: npm ci --ignore-scripts
       - name: Build
         run: npm run build
+      - name: Generate docs
+        run: npm run generate-docs
       - name: Download latest llama.cpp release
         run: node ./dist/cli/cli.js download --release latest --skipBuild
       - name: Upload build artifact
         uses: actions/upload-artifact@v3
         with:
           name: "build"
           path: "dist"
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: "docs"
+          path: "docs"
       - name: Upload llama.cpp artifact
         uses: actions/upload-artifact@v3
         with:
@@ -191,7 +198,12 @@ jobs:
     if: github.ref == 'refs/heads/master'
     runs-on: ubuntu-latest
     concurrency: release-${{ github.ref }}
+    environment:
+      name: npm
+      url: ${{ steps.set-npm-url.outputs.npm-url }}
     permissions:
+      pages: write
+      id-token: write
       contents: write
       issues: write
       pull-requests: write
@@ -213,6 +225,7 @@ jobs:
           mkdir -p llamaBins
           mv artifacts/bins-*/* llamaBins/
           mv artifacts/build dist/
+          mv artifacts/docs docs/
           
           echo "Built binaries:"
           ls llamaBins
@@ -221,4 +234,20 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npx semantic-release
-
+      - name: Set npm package url to GITHUB_OUTPUT
+        id: set-npm-url
+        run: |
+          if [ -f .semanticRelease.npmPackage.deployedVersion.txt ]; then
+            echo "npm-url=https://www.npmjs.com/package/node-llama-cpp/v/$(cat .semanticRelease.npmPackage.deployedVersion.txt)" >> $GITHUB_OUTPUT
+          fi
+      - name: Upload docs to GitHub Pages
+        if: steps.set-npm-url.outputs.npm-url != ''
+        uses: actions/upload-pages-artifact@v2
+        with:
+          name: pages-docs
+          path: docs
+      - name: Deploy docs to GitHub Pages
+        if: steps.set-npm-url.outputs.npm-url != ''
+        uses: actions/deploy-pages@v2
+        with:
+          artifact_name: pages-docs

.gitignore

@@ -4,6 +4,7 @@ node_modules
 .DS_Store
 
 /dist
+/docs
 
 /.env
 /.eslintcache

.releaserc.json

@@ -12,6 +12,9 @@
         }],
         "@semantic-release/release-notes-generator",
         "@semantic-release/npm",
-        "@semantic-release/github"
+        "@semantic-release/github",
+        ["@semantic-release/exec", {
+            "publishCmd": "echo \"${nextRelease.version}\" > .semanticRelease.npmPackage.deployedVersion.txt"
+        }]
     ]
 }

README.md

@@ -18,6 +18,8 @@ If binaries are not available for your platform, it'll fallback to download the
 To disable this behavior set the environment variable `NODE_LLAMA_CPP_SKIP_DOWNLOAD` to `true`.
 
 ## Documentation
+### [API reference](https://withcatai.github.io/node-llama-cpp/modules.html)
+
 ### Usage
 #### As a chatbot
 ```typescript
@@ -129,7 +131,7 @@ console.log("AI: " + a1);
 ```
 
 ### CLI
-```txt
+```
 Usage: node-llama-cpp <command> [options]
 
 Commands:
@@ -140,11 +142,11 @@ Commands:
 
 Options:
   -h, --help     Show help                                                                 [boolean]
-  -v, --version  Show version number                                                       [boolean]                                                [boolean]
+  -v, --version  Show version number                                                       [boolean]
 ```
 
 #### `download` command
-```txt
+```
 node-llama-cpp download
 
 Download a release of llama.cpp and compile it
@@ -162,7 +164,7 @@ Options:
 ```
 
 #### `build` command
-```txt
+```
 node-llama-cpp build
 
 Compile the currently downloaded llama.cpp
@@ -175,7 +177,7 @@ Options:
 ```
 
 #### `clear` command
-```txt
+```
 node-llama-cpp clear [type]
 
 Clear files created by llama-cli
@@ -187,7 +189,7 @@ Options:
 ```
 
 #### `chat` command
-```txt
+```
 node-llama-cpp chat
 
 Chat with a LLama model