From 3506ce29b145b788989b2cf27ccbdababd619bbf Mon Sep 17 00:00:00 2001 From: Amit Sharma Date: Wed, 24 Jul 2024 20:27:22 +0530 Subject: [PATCH] Add JS hosted documentation (#1678) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add JS hosted documentation * Update .github/workflows/docs.yml * Update .github/workflows/docs.yml --------- Co-authored-by: Clémentine --- .eslintignore | 1 + .github/workflows/docs.yml | 27 ++ .gitignore | 3 + README.md | 2 +- package.json | 2 + tsconfig.json | 5 +- typedoc.json | 31 +++ typedoc/style.css | 556 +++++++++++++++++++++++++++++++++++++ yarn.lock | 57 ++++ 9 files changed, 681 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 typedoc.json create mode 100644 typedoc/style.css diff --git a/.eslintignore b/.eslintignore index f45ee7ae7..2b2121dbb 100644 --- a/.eslintignore +++ b/.eslintignore @@ -5,3 +5,4 @@ dist # @TODO: I'm not sure what's going on here, we're importing # in JS file from TS files, better left ignored for now /playgrounds +/docs diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..97b7f8526 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,27 @@ +name: Build documentation + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install dependencies + run: yarn install + + - name: Generate Documentation + run: yarn build:docs + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs + force_orphan: true diff --git a/.gitignore b/.gitignore index 8c37ef01f..2814bdb2b 100644 --- a/.gitignore +++ b/.gitignore @@ -65,6 +65,9 @@ typings/ # Output of 'npm pack' *.tgz +# Generated Docs +docs/ + # Yarn Integrity file .yarn-integrity diff --git a/README.md b/README.md index 33cdf3f1d..0acbe8747 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ ## 📖 Documentation -This readme contains all the documentation you need to start using this Meilisearch SDK. +This readme and [Meilisearch JS documentation website](https://meilisearch.github.io/meilisearch-js/) contains all the information you need to start using this Meilisearch SDK. For general information on how to use Meilisearch—such as our API reference, tutorials, guides, and in-depth articles—refer to our [main documentation website](https://www.meilisearch.com/docs/). diff --git a/package.json b/package.json index 8e54cab9c..5b27f003a 100644 --- a/package.json +++ b/package.json @@ -33,6 +33,7 @@ "clear_jest": "jest --clearCache", "cleanup": "shx rm -rf dist/", "build": "yarn cleanup && rollup -c && rollup -c --environment NODE_ENV:production", + "build:docs": "typedoc", "watch": "yarn cleanup && rollup -c --watch", "postbuild": "yarn size && yarn typingsheader", "test": "yarn clear_jest && jest --runInBand --verbose", @@ -105,6 +106,7 @@ "rollup-plugin-typescript2": "^0.35.0", "shx": "^0.3.2", "ts-jest": "^29.1.1", + "typedoc": "^0.25.13", "typescript": "^5.3.3" } } diff --git a/tsconfig.json b/tsconfig.json index 4e1ff1c5a..dea3cc9ce 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -22,6 +22,7 @@ "target": "es2022", "lib": ["ESNext", "dom"], "strict": true, - "noImplicitReturns": true - } + "noImplicitReturns": true, + }, + "include": ["src"], } diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 000000000..3d4dc1392 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,31 @@ +{ + "name": "Meilisearch JS", + "entryPoints": ["./src"], + "out": "./docs", + "customCss": "./typedoc/style.css", + "groupOrder": [ + "References", + "Modules", + "Namespaces", + "Enumerations", + "Enumeration Members", + "Classes", + "Interfaces", + "Type Aliases", + "Constructors", + "Properties", + "Variables", + "Functions", + "Accessors", + "Methods" + ], + "navigation": { + "includeCategories": true, + "includeGroups": true + }, + "navigationLinks": { + "Docs": "https://www.meilisearch.com/docs", + "GitHub": "https://github.com/meilisearch/meilisearch-js" + }, + "githubPages": true +} diff --git a/typedoc/style.css b/typedoc/style.css new file mode 100644 index 000000000..2b190e6de --- /dev/null +++ b/typedoc/style.css @@ -0,0 +1,556 @@ +:root { + --font-family-code: "JetBrains Mono", Menlo, Consolas, Monaco, Liberation Mono, + Lucida Console, monospace; + --font-family-system: Inter, Roboto, "Helvetica Neue", "Arial Nova", + "Nimbus Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, + Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", + "Segoe UI Symbol"; + --shadow-overlay: 0px 10px 15px rgba(32, 37, 46, 0.15), + 0px 3px 5px rgba(23, 26, 33, 0.21); +} + +body { + font-size: 15px; + font-family: var(--font-family-system); +} + +:root { + --color-active-menu-item: linear-gradient( + 90deg, + hsla(0, 0%, 100%, 0.08), + hsla(0, 0%, 100%, 0.039) + ); + + --color-title: #ff5caa; + --color-text: white; + --color-icon-background: #0006; + + --color-ts-project: #2548b6; + + --color-ts-enum: #0585ae; + --color-ts-enum-background: transparent; + + --color-ts-namespace: #1305ae; + --color-ts-namespace-background: transparent; + + --color-ts-variable: #78059e; + --color-ts-variable-background: transparent; + + --color-ts-type-parameter: #51e1d3; + --color-ts-type-keyword: #ff7b72; + + --color-ts-function: #6639ba; + --color-ts-function-background: transparent; + + --color-ts-class: #f8c555; + --color-ts-class-background: transparent; + + --color-ts-interface: #0483cc; + --color-ts-interface-background: transparent; + + --color-ts-type-alias: #ae05a7; + --color-ts-type-alias-background: transparent; + + --color-accent: #6639ba; + --code-background: linear-gradient( + 90deg, + hsla(0, 0%, 100%, 0.08), + hsla(0, 0%, 100%, 0.039) + ); + --color-background: linear-gradient( + 180deg, + #14002d -5px, + #1c0040 1000px, + #0e0021 + ); + --color-background-secondary: linear-gradient( + 150.53deg, + rgba(255, 92, 178, 0.25) -2px, + rgba(107, 86, 220, 0.073) 300px, + rgba(20, 0, 45, 0) 800px + ), + linear-gradient(180deg, #14002d -5px, #1c0040 1000px, #0e0021); + --color-background-nav-mobile: #1c0040; + + /* Highlight Colors */ + --hl-0: #d2a8ff; + --hl-1: #ff7b72; + --hl-2: #51e1d3; + --hl-3: #ff7b72; + --hl-4: #f8c555; + --hl-5: #ff7b72; + --hl-6: #d2a8ff; + + --color-text-aside: rgb(255, 92, 178); + --color-link: rgb(255, 92, 178); + --color-separator: transparent; + --color-background-search-results: linear-gradient( + 150.53deg, + rgba(255, 92, 178, 0.25) -0.45%, + rgba(107, 86, 220, 0.073) 13.45%, + rgba(20, 0, 45, 0) 30.7% + ), + linear-gradient(180deg, #1d0042 -0.71%, #1d0042 81.38%, #1c0040); + + --primary-bg-color-transparent: #f7f9fad9; +} + +*::selection { + background: var(--color-accent); + color: white; +} + +pre { + border: none; + padding: 0; +} + +pre + pre { + margin-top: 0.5rem; +} + +pre code { + display: block; + padding: 1rem; +} + +pre > button { + border-radius: 4px; + border: none; + background: var(--color-background); + padding: 4px 8px; + cursor: pointer; +} + +hr { + display: block; + height: 1px; + border: 0; + border-top: 1px solid var(--color-separator); + margin: 1em 0; + padding: 0; +} + +*::-webkit-scrollbar { + display: none; +} + +h4 { + margin: 1.2rem 0; +} + +.container { + --color-background: var(--color-background-nav-mobile); + background: var(--color-background); +} + +@media screen and (max-width: 769px) { + .container { + background: var(--color-background); + } +} + +.container-main { + min-height: calc(100vh - 4rem); +} + +@media (min-width: 770px) { + #docs-header { + height: 61px; + background: var(--primary-bg-color-transparent); + } +} + +@media (max-width: 480px) { + #docs-header { + height: 95px; + } +} + +.container-main .col-content { + padding: 0 2rem; + margin-top: 2rem; +} + +@media (min-width: 770px) { + .container-main { + margin: 0; + } +} + +a.tsd-index-link { + font-size: 0.9rem; +} + +.tsd-navigation { + font-size: 14px; + padding-top: 1rem; +} + +.tsd-nested-navigation { + margin-left: 0; +} + +.tsd-index-content > :not(:first-child) { + padding: 0 1rem; +} + +/* Hide visibility selector and themer */ +.tsd-theme-toggle { + display: none; +} + +.tsd-navigation .tsd-kind-icon { + height: 1.5rem; + width: 1.5rem; + min-height: 20px; + min-width: 20px; + margin-right: 0.4rem; +} + +.tsd-navigation a, +.tsd-navigation summary > span, +.tsd-page-navigation a { + display: block; +} + +.container .site-menu { + height: 100%; + border-right: 1px solid var(--color-separator); + overflow: auto; +} + +.container .site-menu > div { + height: 100%; +} + +@media (min-width: 770px) and (max-width: 1399px) { + .site-menu { + margin-top: 0; + } +} + +.page-menu { + border-left: 1px solid var(--color-separator); + background-image: var(--sidebar-background); +} + +.tsd-signature, +.tsd-kind-parameter, +.tsd-kind-property, +.tsd-parameter h5, +.tsd-signature-type, +.tsd-signature-symbol, +code, +pre { + font-family: var(--font-family-code); +} + +.tsd-kind-icon ~ span { + font-family: var(--font-family-system); +} + +#tsd-search .results span.parent { + color: var(--color-text); +} + +.tsd-navigation .tsd-accordion-summary, +.tsd-accordion-summary > * { + display: flex; + align-items: center; +} + +.tsd-signatures .tsd-signature, +.tsd-signature { + border: none; + border-radius: 10px; + background: var(--code-background); +} + +.tsd-signature { + padding: 1rem; +} + +.tsd-signature-keyword { + color: var(--color-ts-type-keyword); +} + +.tsd-signature-type { + color: var(--color-ts-type-parameter); +} + +.tsd-signature-type.tsd-kind-class { + color: var(--color-ts-class); +} + +.tsd-signature-type.tsd-kind-type-alias { + color: var(--color-ts-type-alias); +} + +.tsd-signature-type.tsd-kind-type-parameter { + color: var(--color-ts-type-parameter); +} + +.tsd-signature-type.tsd-kind-type-interface { + color: var(--color-ts-interface); +} + +.tsd-signature-type.tsd-kind-type-enum { + color: var(--color-ts-enum); +} + +a.tsd-signature-type { + text-decoration: underline; + text-decoration-thickness: from-font; + font-style: normal; +} + +a.tsd-signature-type:hover { + text-decoration: none; +} + +.tsd-returns-title, +ul.tsd-parameter-list h5, +ul.tsd-type-parameter-list h5, +.tsd-parameters h5 { + font-size: 0.9rem; +} + +.tsd-parameters h5 { + margin: 0.5rem 0; +} + +.tsd-accordion-details { + margin: 0 1rem; +} + +.tsd-accordion-details .tsd-index-heading { + display: flex; + align-items: center; + text-transform: uppercase; + font-size: 0.9rem; + letter-spacing: 0.3px; +} + +.tsd-index-heading svg { + margin-right: 5px; +} + +ul.tsd-hierarchy li { + margin-top: 0.4rem; +} + +.tsd-panel.tsd-member { + margin-bottom: 2rem; +} + +.tsd-panel h4 { + font-weight: 600; +} + +.tsd-panel-group { + margin: 2.5rem 0; +} + +code.tsd-tag { + border: none; + margin-bottom: -5px; + font-size: 75%; +} + +.site-menu .tsd-navigation { + overflow-y: auto; + height: calc(100% - 65px); +} + +.tsd-navigation a, +.tsd-navigation summary > span, +.tsd-page-navigation a { + display: flex; +} + +#tsd-search { + position: sticky; + top: 0; + z-index: 1; +} + +@media (min-width: 770px) { + #tsd-search { + padding: 1rem 1rem 1rem 0; + } +} + +#tsd-search.has-focus { + background: none; +} + +#tsd-search input { + box-shadow: none; + font-size: var(--font-size-regular); + border: 1.5px solid var(--separator-color); + font-weight: 400; + cursor: text; + padding: 0.4rem 1rem; + width: 100%; +} + +#tsd-search .results li:nth-child(even), +#tsd-search .results li { + font-size: 0.8rem; + background-color: unset; + padding: 0.1rem 0.4rem; +} + +#tsd-search .results li a { + color: inherit; + text-decoration: none; +} + +#tsd-search .results li.current:not(.no-results), +#tsd-search .results li:hover:not(.no-results) { + background: var(--color-separator); +} + +#tsd-search .results li:not(:last-of-type) { + border-bottom: 0.5px solid var(--color-separator); +} + +#tsd-search .results li:not(:last-of-type) { + border-bottom: 0.5px solid var(--color-separator); +} + +#tsd-search .results { + max-width: 800px; + overflow: hidden; + background: var(--color-background-search-results); + top: 50px; + padding: 1rem; + border-radius: 8px; +} + +@media (min-width: 770px) { + #tsd-search .results { + min-width: 380px; + } +} + +#tsd-search .results .no-results { + padding: 1rem; +} + +.tsd-page-navigation { + font-size: 14px; +} + +.tsd-page-navigation h3 { + margin-bottom: 1rem; +} + +.tsd-internal-warning-banner { + border-radius: 10px; + background: var(--code-background); + margin-bottom: 1rem; + padding: 1rem; +} + +#tsd-search { + transition: background-color 0.1s; +} + +#tsd-search .field input, +#tsd-search .title, +#tsd-toolbar-links a { + transition: opacity 0.1s; +} + +#tsd-search .title { + top: 0; + color: var(--color-title); +} + +@media screen and (min-width: 770px) { + #tsd-search .title { + top: -15px; + } +} + +#tsd-search input:focus { + border: 1.5px solid var(--selected-stroke-color); +} + +.tsd-navigation a.current { + font-weight: 600; + border-radius: 5px; +} + +.tsd-page-toolbar { + background: var(--color-background-secondary); + backdrop-filter: blur(10px); + transition: transform 0.1s ease-in-out; + border-bottom: 1px solid white; +} + +#tsd-search-field { + font-family: var(--font-family-code); + font-size: 1rem; +} + +/* Remove nested padding */ +ul > li:only-child > ul:only-child { + padding: 0; +} + +.tsd-page-navigation ul { + padding-left: 1rem; +} + +.tsd-kind-icon-custom { + background: #ecdceb; + padding: 0 5px; + border-radius: 3px; + font-family: var(--font-family-code); + font-weight: bold; + color: #9f0499; + line-height: 1.4; + margin-right: 2px; +} + +[id^="icon-"] rect { + rx: 8px; +} + +[id^="icon-"] path { + stroke-width: 0.5px; +} + +#icon-chevronDown path { + fill: #4b4e5c; + stroke: white; + stroke-width: 1.5px; +} + +.tsd-breadcrumb { + font-family: var(--font-family-code); + font-size: 14px; +} + +.tsd-breadcrumb li:after { + color: white; +} + +.container { + padding: 0 1rem; +} + +@media (min-width: 770px) { + .tsd-filter-visibility { + padding-left: 1.5rem; + } +} + +#icon-chevronDown path { + fill: #fff; + stroke: none; + stroke-width: 1.5px; +} diff --git a/yarn.lock b/yarn.lock index e104911a2..2355d0aa6 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2240,6 +2240,11 @@ ansi-regex@^6.0.1: resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-6.0.1.tgz#3183e38fae9a65d7cb5e53945cd5897d0260a06a" integrity sha512-n5M855fKb2SsfMIiFFoVrABHJC8QtHwVx+mHWP3QcEqBHYienj5dHSgjbxtC0WEZXYt4wcD6zrQElDPhFuZgfA== +ansi-sequence-parser@^1.1.0: + version "1.1.1" + resolved "https://registry.yarnpkg.com/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz#e0aa1cdcbc8f8bb0b5bca625aac41f5f056973cf" + integrity sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg== + ansi-styles@^3.2.1: version "3.2.1" resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-3.2.1.tgz#41fbb20243e50b12be0f04b8dedbf07520ce841d" @@ -4357,6 +4362,11 @@ json5@^2.2.3: resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.3.tgz#78cd6f1a19bdc12b73db5ad0c61efd66c1e29283" integrity sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg== +jsonc-parser@^3.2.0: + version "3.2.1" + resolved "https://registry.yarnpkg.com/jsonc-parser/-/jsonc-parser-3.2.1.tgz#031904571ccf929d7670ee8c547545081cb37f1a" + integrity sha512-AilxAyFOAcK5wA1+LeaySVBrHsGQvUFCDWXKpZjzaL0PqW+xfBOttn8GNtWKFWqneyMZj41MWF9Kl6iPWLwgOA== + jsonfile@^6.0.1: version "6.1.0" resolved "https://registry.yarnpkg.com/jsonfile/-/jsonfile-6.1.0.tgz#bc55b2634793c679ec6403094eb13698a6ec0aae" @@ -4514,6 +4524,11 @@ lru-cache@^6.0.0: dependencies: yallist "^4.0.0" +lunr@^2.3.9: + version "2.3.9" + resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1" + integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow== + magic-string@^0.27.0: version "0.27.0" resolved "https://registry.yarnpkg.com/magic-string/-/magic-string-0.27.0.tgz#e4a3413b4bab6d98d2becffd48b4a257effdbbf3" @@ -4540,6 +4555,11 @@ makeerror@1.0.12: dependencies: tmpl "1.0.5" +marked@^4.3.0: + version "4.3.0" + resolved "https://registry.yarnpkg.com/marked/-/marked-4.3.0.tgz#796362821b019f734054582038b116481b456cf3" + integrity sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A== + mdast-util-from-markdown@^2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.0.tgz#52f14815ec291ed061f2922fd14d6689c810cb88" @@ -4820,6 +4840,13 @@ minimatch@^5.0.1: dependencies: brace-expansion "^2.0.1" +minimatch@^9.0.3: + version "9.0.4" + resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-9.0.4.tgz#8e49c731d1749cbec05050ee5145147b32496a51" + integrity sha512-KqWh+VchfxcMNRAJjj2tnsSJdNbHsVgnkBhTNrW7AjVo6OvLtxw8zfT9oLw1JSohlFzJ8jCoTgaoXvJ+kHt6fw== + dependencies: + brace-expansion "^2.0.1" + minimist@^1.2.0, minimist@^1.2.3: version "1.2.7" resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.7.tgz#daa1c4d91f507390437c6a8bc01078e7000c4d18" @@ -5534,6 +5561,16 @@ shelljs@^0.8.4: interpret "^1.0.0" rechoir "^0.6.2" +shiki@^0.14.7: + version "0.14.7" + resolved "https://registry.yarnpkg.com/shiki/-/shiki-0.14.7.tgz#c3c9e1853e9737845f1d2ef81b31bcfb07056d4e" + integrity sha512-dNPAPrxSc87ua2sKJ3H5dQ/6ZaY8RNnaAqK+t0eG7p0Soi2ydiqbGOTaZCqaYvA/uZYfS1LJnemt3Q+mSfcPCg== + dependencies: + ansi-sequence-parser "^1.1.0" + jsonc-parser "^3.2.0" + vscode-oniguruma "^1.7.0" + vscode-textmate "^8.0.0" + shx@^0.3.2: version "0.3.3" resolved "https://registry.yarnpkg.com/shx/-/shx-0.3.3.tgz#681a88c7c10db15abe18525349ed474f0f1e7b9f" @@ -5888,6 +5925,16 @@ typedarray-to-buffer@^3.1.5: dependencies: is-typedarray "^1.0.0" +typedoc@^0.25.13: + version "0.25.13" + resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.13.tgz#9a98819e3b2d155a6d78589b46fa4c03768f0922" + integrity sha512-pQqiwiJ+Z4pigfOnnysObszLiU3mVLWAExSPf+Mu06G/qsc3wzbuM56SZQvONhHLncLUhYzOVkjFFpFfL5AzhQ== + dependencies: + lunr "^2.3.9" + marked "^4.3.0" + minimatch "^9.0.3" + shiki "^0.14.7" + typescript@^5.3.3: version "5.3.3" resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.3.3.tgz#b3ce6ba258e72e6305ba66f5c9b452aaee3ffe37" @@ -6025,6 +6072,16 @@ v8-to-istanbul@^9.0.1: "@types/istanbul-lib-coverage" "^2.0.1" convert-source-map "^2.0.0" +vscode-oniguruma@^1.7.0: + version "1.7.0" + resolved "https://registry.yarnpkg.com/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz#439bfad8fe71abd7798338d1cd3dc53a8beea94b" + integrity sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA== + +vscode-textmate@^8.0.0: + version "8.0.0" + resolved "https://registry.yarnpkg.com/vscode-textmate/-/vscode-textmate-8.0.0.tgz#2c7a3b1163ef0441097e0b5d6389cd5504b59e5d" + integrity sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg== + w3c-xmlserializer@^4.0.0: version "4.0.0" resolved "https://registry.yarnpkg.com/w3c-xmlserializer/-/w3c-xmlserializer-4.0.0.tgz#aebdc84920d806222936e3cdce408e32488a3073"