web-dev-qa-db-ja.com

JSDocのデフォルトの「ホーム」テキストとコンテンツ

Node.jsから基本的なJSDocコンパイル/レンダリングを実行した後：

jsdoc file1.js file2.js

ディレクトリ「out」内のデフォルトのテンプレートを使用して、適切にフォーマットされたドキュメントを取得します。ほとんどすべてが期待どおりです！

ただし、ドキュメントを開くと、index.htmlページに常に「ホーム」と表示され、最初のページにコンテンツがなく、サイドバーのナビゲーションに「ホーム」が表示されます。

「ホーム」を置き換えるために、プロジェクトの名前をどこでどのように表記しますか？プロジェクトの説明、作者、著作権情報も見たいです。

JSDocで行う最も基本的なことのように思えますが、情報が見つかりません。インターネットで見つけたランダムな記事に基づいて、次のことを試しました。

/** 
 * This JavaScript file contains foo bar baz...
 * 
 * @projectname Project Name
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

しかし、私は愛を得ません。

[追加するために編集：]

@file/@fileOverview/@overview（すべての同義語）ディレクティブを発見しました。これは、各ファイルの著作権/作成者情報を記述および設定できるため、いくらか役立ちます。

/** 
 * @file Project description which renders below the individual filename and therefore isn't a real overview blurb.
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

それでも解決すべき2つの「問題」が残っています。

  1. 概要の説明。 @fileは私のニーズのほとんどを処理すると思いますが、ファイルごとなので、インクルードされたファイルの説明の前に表示される「紹介」タイプの段落または概要段落が必要です。

  2. その「ホーム」テキストをカスタムテキストに置き換える

javascriptjsdocjsdoc3
23
Greg Pettit

ホームページを生成する

マークダウンファイルREADME.mdを作成します

Jsdocの生成：

$ jsdoc path/to/js path/to/readme/README.md

この訪問の詳細を読むには 公式ドキュメント

「ホーム」テキストを変更する

これは適切な方法ではないと思いますが、これは機能します。

プロジェクトにjsdocがインストールされている場合、作業ディレクトリのテンプレートファイルを検索します。

./node_modules/jsdoc/templates/default/publish.js

次に、検索コマンドで「ホーム」を検索し、テキストに置き換えます。次のステップは、jsdocを生成するときにテンプレートを指定することです。

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/
24
T.Chmelevskij

コメントできないので、「\ npm\node_modules\jsdoc \」にあるファイルの指示に基づいて、デフォルトのテンプレートを変更せずに元の質問のすべてのことを行う方法を明確にするために、ここにメモを追加します。テンプレート」フォルダ。独自のテンプレートを作成する方法を説明しています。生成されたjsドキュメントの「ホーム」見出しをプロジェクト固有の見出し（「MyDescription」など）に変更し、メインページの上部に概要の宣伝文句を含める手順の概要を以下に示します。

ステップ

  1. まず、jsドキュメントのメインページの上部に一般的な概要を表示するには、上記の回答とリンクに従って、Markdownで記述されたREADME.mdという名前の単純なテキストファイルを作成します。上記のようにそのファイルへのパスがコマンドラインに含まれている場合、またはconf.jsonという名前のファイルに参照が追加されている場合は、テキスト全体がページの上部に表示されます。この場合、jsdoc -c pathTo\conf.jsonを使用できます。コマンドライン（以下の項目4の例を参照）。 （リンクで説明されているように、Markdownにあり、jsdocにファイルの場所を指示する限り、任意の名前または拡張子でファイルを作成できます）。
  2. デフォルトテンプレート（\npm\node_modules\jsdoc\templates\default）のフォルダと内容を新しいディレクトリにコピーし、新しいフォルダの名前をmyTemplateのように変更します。
  3. 上記のアドバイスを使用してChange'Home 'text、新しいmyTemplateフォルダー内のpublish.jsという名前のファイルを検索し、「Home」を「MyDescription」に置き換えます。ここで注意すべき2つのポイント：ファイル名はpublish.jsのままにする必要があり、「Home」は元の「publish.js」の2か所の[.____]行に表示されます。
    var nav = '<h2> <ahref = "index.html">ホーム</a> </ h2>';
    およびgenerate('Home',...で始まる行。

  4. カスタムテンプレート（myTemplateフォルダー）と概要ファイル（ "README.md"）の場所をjsdocジェネレーターに伝えます。コマンドラインに-t pathTo\myTemplateを追加するか、テキストエディタでjsdoc -c pathTo\conf.jsonという名前のファイルを作成する場合は、非常に短いコマンドラインconf.jsonを使用できます。これは、ドキュメントのソース、宛先などを指定します。このファイルは、ドキュメントジェネレータに「ソース」セクションでREADME.mdを使用するように指示することで概要をメインページに配置し、新しいmyTemplateフォルダを使用して見出しを「ホーム」から新しい見出し「MyDescription」に変更します。 「opts」セクションにあります。

    {
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "opts": {
        "template": "pathTo/myTemplate",
        "destination": "pathTo/myJScriptDocs",
        "recurse": true
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_",
        "include": ["pathTo/myJSSources", "pathTo/README.md"]
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}
5
user4785649

@file（または@fileOverview）を1つ以上のソースファイルに追加することもできます。

ファイルの概要セクションはすべて、JSDocホームページに含まれます。 READMEもJSDocにフィードすると、ファイルの概要はReadmeコンテンツの後に配置されます。

例：

/**
 * @file index.js is the root file for the example.
 * It kicks things off.
 * @author Your name goes here
 * @see <a href="https://developers.docusign.com">DocuSign Developer Center</a>
 */
3
Larry K

'Home'はデフォルトのテンプレートでハーコードされている（インデックスの生成時にtitleとして渡される）ため、このタイトルを変更するために設定できる変数または構成はありません。

複数の人がドキュメントを生成/編集している場合、node_modulesを編集するのは当然のことです。

Layout.tmpl（または使用している場合は完全なカスタムテンプレート）を作成し、JSDocをそのテンプレート（CLIオプションまたは構成ファイル）にポイントして、<?js= title ?>を<?js= title==='Home' ? 'Your Title' : title ?>に置き換えるだけで十分です。

2
Petra

ホームページでも同様の問題が発生しました。 JSDOCページを生成したかった小さな社内JavaScriptライブラリは、単なるグローバル関数のコレクションであり、ホームページをまったく表示したくありませんでした。 global.htmlページのみを表示したい。

NPMを使用してJSDOCをインストールするため、グローバルページをカスタマイズするためだけにモジュール全体を複製したくありませんでした。代わりに、レイアウトページだけを別のディレクトリにコピーし、jsdoc.json構成ファイルで次のように指定しました。

"templates" : {
"default": {
  "layoutFile": "config/layout.tmpl"
}

}

次に、layout.tmplを編集して、home.htmlページへのリンクを表示しないスタイルルールを使用して<style>タグを追加しました。

  nav > h2 {
    display: none;
  }
1
Stefan Musarra