JSDoc के साथ शुरुआत

clean-jsdoc-theme एक JSDoc template है। JSDoc वही करता है जो वह हमेशा करता है — आपके source को parse करना और doc comments इकट्ठा करना — और फिर template के publish function को कमान सौंप देता है, जहाँ से यह theme कमान सँभालकर static site बनाता है। आप बस JSDoc को theme पर इंगित करते हैं, और काम पूरा।

यह कैसे जुड़ता है। JSDoc किसी template को उसके exported publish function को call करके load करता है — यहाँ वह publish(data, opts, tutorials) है (package का main, dist/publish.js)। यह आपकी doclet collection लेता है और उसे setu → dwar pipeline से गुज़ारता है। हर stage क्या करता है, यह जानने के लिए Packages देखें।

Install और build

1. 1
   Install

   JSDoc और theme को dev dependencies के रूप में install करें:

   npmpnpm

   CODE

   कॉपी करें

   npm install --save-dev jsdoc clean-jsdoc-theme

2. 2
   Configure

   अपने project root में एक jsdoc.json जोड़ें। एक छोटा पर वास्तविक शुरुआती बिंदु:

   CODE

   कॉपी करें

   {
     source: { include: ["./src", "./README.md"] },
   
     // ज़रूरी — नीचे दी गई चेतावनी देखें।
     plugins: ["plugins/markdown"],
   
     opts: {
       // JSDoc को theme पर इंगित करें। CLI पर `jsdoc -t <path>` के समतुल्य।
       template: "node_modules/clean-jsdoc-theme/dist",
       destination: "dist",
       recurse: true,
       readme: "./README.md",
       siteName: "My Library",
     },
   }

   plugins/markdown plugin ज़रूरी है। JSDoc आपके doc comments के Markdown को theme के देखने से पहले ही HTML में render कर देता है, और theme उसी HTML को consume करता है (देखें from-html.ts)। इसके बिना descriptions कच्चे, बिना-format किए text के रूप में पहुँचती हैं।

3. 3
   Build

   config के विरुद्ध JSDoc चलाएँ:

   CODE

   कॉपी करें

   npx jsdoc -c jsdoc.json

4. 4
   Serve

   site dist/ में लिखी जाती है। dist/index.html खोलें, या folder को serve करें (Pagefind का full-text index load होने के लिए HTTP चाहिए):

   CODE

   कॉपी करें

   npx serve dist

एक पूर्ण, चलने-योग्य JSDoc setup repo में examples/basic पर मौजूद है — इसकी jsdoc.json और source comments इस page की हर बात का reference हैं।

options कहाँ जाते हैं

theme options आपके jsdoc.json में opts के नीचे, JSDoc के अपने options के साथ रहते हैं। पहले-पहल काम आने वाले कुछ — पूरी सूची, TypeDoc रूप के साथ-साथ, के लिए Configuration page देखें।

कुछ options — outputSourceFiles और sourceLinkToComment — सिर्फ़ JSDoc के लिए हैं और opts के नहीं, बल्कि templates.default के नीचे बैठते हैं (theme उन्हें jsdoc/env से पढ़ता है)। ये Configuration page पर चिह्नित हैं।

कई भाषाएँ

theme आपके docs को कई भाषाओं में render कर सकता है — हर locale के लिए अपना static site (default root पर, बाक़ी /<locale> के नीचे), साथ में एक header language switcher। आप opts.locales में अपनी locales declare करते हैं, फिर clean-jsdoc CLI से translation + per-locale builds चलाते हैं:

opts: {
  locales: [
    { code: "en", name: "English" },
    { code: "ja", name: "日本語" },
  ],
  defaultLocale: "en",
}

बिना locales के build पर कोई असर नहीं पड़ता। पूरे workflow (extract → translate → build) के लिए Localize your docs देखें, और locales / defaultLocale reference भी।

आगे के कदम

• Build an API reference — क्या एक page बनता है, source-file viewer, और Source: file:line links।
• Build a guides site और Combine guides + API — उसी site में हाथ से लिखे Markdown जोड़ें।
• Structure your sidebar — @category, @order, और sidebar options।
• Authoring — callouts, steps, tabs, और embeds जिन्हें आप comments और prose में इस्तेमाल कर सकते हैं।
• Localize your docs — site को कई भाषाओं में ship करें।
• TypeScript पसंद है? देखें TypeDoc Getting Started — वही output, अलग toolchain।