web-dev-qa-db-ja.com

GitHubPagesのJavaScriptAPIドキュメントを生成するにはどうすればよいですか

他の言語のAPIドキュメントを生成するための優れたオプションはたくさんありますが、GitHubPagesでホストしたいJavaScriptAPIのソリューションをまだ見つけていません。 JSDoc を使用できるようですが、Jekyllマークアップを出力するカスタムプラグインを作成する必要があります。

また、コードのURLをGitHub自体にリンクしてほしい。私は jsdoc-githubify を見つけました。これは、リンクを変更するために出力を変更しますが、より制御しやすい、より簡単なオプションを好みます。

独自のJSDocプラグインを作成する必要がありますか、それとも私が見逃していたより良い解決策がありますか？人々はこれに何を使用しますか？

javascriptdocumentationjekyllgithub-pagesjsdoc
31
Andy Armstrong

Grunt に精通している場合は、 grunt-jsdoc を使用して.htmlドキュメントを簡単に生成できます。

  • JSDoc を使用してコードを文書化します。
  • grunt-jsdoc を使用します。これは内部で jsdoc を使用してコードドキュメントを生成します。
  • これにより、ソースコードがHTMLで出力され、ドキュメント内に、一般公開されている各メンバーのコード行へのリンクが含まれます。
  • JSDocの@linkディレクティブを使用するだけで、リンクを制御することもできます。
    See {@link https://github.com/onury|My GitHub Profile}。

以下のGruntfileの例を参照してください。
これはすべての JSDoc CLIオプション をサポートすることに注意してください。

grunt.initConfig({
    'jsdoc': {
        dist: {
            src: ['./src/core/mylib.js'],
            options: {
                destination: './doc/html'
            }
        }
    }
});

そして、このタスクをgrunt jsdocで実行します。または、grunt-contrib-watchプラグインを追加して、ファイルが変更されるたびに自動実行することもできます。

テンプレートとスタイリング：

  • いつでもCSSファイルで遊んで、自分の好みに合わせて上書きすることができます。
  • または、grunt-jsdocで使用できるBootstrapに基づくJSDoc3の docstrap テンプレートを使用できます。

ドキュメントに Jekyll を使用：

ネイティブでサポートされていますが、GitHubページにJekyllを使用する必要はありません。 Jekyllは、実際には静的なWebサイトまたはブログ用に設計されています。しかし、それはマークダウンファイルを取ることができます。したがって、最初にコードからgithub風味のマークダウンファイルを jsdoc-to-markdown （Gruntプラグイン grunt-jsdoc2md ）を介して作成し、次に configure それに応じてJekyllプロジェクト。

ただし、Jekyllをインストールして構成するには、追加の作業が必要になることに注意してください。以下は、良い 記事 と サンプルプロジェクト です。

更新：

これに答えた後、私はドキュメントを簡単に作成するためのツールに取り組み始めました。今、それはここに投稿してあなたがそれを好きかどうか見るのに十分成熟しています。それは Docma と呼ばれます。

Docmaの主な機能は次のとおりです。 JSDocファイルとMarkdownファイルの両方をHTMLドキュメントに解析し、 Webアプリ、非常に構成可能で、Github Pagesでうまく機能します。

Docmaドキュメントはこちら を参照してください。これもDocmaで構築され、GitHubPagesでホストされています。

Docmaが生成したSPAのスクリーンショットの例：

enter image description here

22
Onur Yıldırım

私はこれがあなたが探しているものだと思います： http://jsdox.org/

jsdoxは単純なjsdoc3ジェネレーターです。 javascriptファイルからjsdoc3のサブセットに基づいてドキュメントタグを取得し、マークダウンファイルを生成します。

5
Xavi Magrinyà

JSDox はまさにあなたが探しているものです。

2
Charlie

私はSwaggerのファンです： https://github.com/swagger-api/swagger-ui ＆ http://swagger.io/ 。

APIドキュメントだけではないので、やり過ぎかもしれませんが、APIをドキュメント化するという素晴らしい仕事をしています。

1
obi1

それを簡素化しようとしています

  • GitHubページで、Jekyllマークアップを出力するAPIドキュメントを生成します。

    {% raw %}タグを付けて液体テンプレートをエスケープします。

    {% raw %}
   I want to be {{escaped}}.
{% endraw %}

    参照：github/.com/Shopify/liquid/wiki/Liquid-for-Designers＃raw

    参照：jekyllrb/.com/docs/github-pages /＃project-pages

    2つのブランチを作成します。1つはgh-pagesのマスター用で、masterブランチは.mdファイルを含み、gh-pagesは静的に生成された.htmlファイルを含みます。ローカルコンピューターの場合：現在のプロジェクトフォルダーの$ jekyll buildは./_siteに生成されます。

    gitHubにアップロードします。

    ジェキル

    • マスターブランチ：github/.com/jekyll/jekyll
    • gh-pagesブランチ：github/.com/jekyll/jekyll/tree/gh-pages

    fb/react

    • マスターブランチ：github/.com/facebook/react/edit/master/docs/docs/ref-01-top-level-api.md
    • gh-pagesブランチ：github/.com/facebook/react/blob/gh-pages/docs/top-level-api.html

  • ページのURLはGitHubドキュメント自体にリンクしています。

    _layoutsフォルダー（htmlテンプレート）にリンクを追加 ドキュメントページの「GitHubで編集」 これは それに関するブログ投稿

    • 0
    blinksmith

    私はしばらくそれを更新していませんが、 https://github.com/punkave/dox-foundation は別のオプションです。 gh-pagesブランチにコミットできるHTMLファイルを生成するだけです。

    0
    mattmcmanus