LoginSignup
9
13

More than 5 years have passed since last update.

@hibohiboo(ひぼ)

sphinx, jsdoc, esdoc, typedocをdockerを使ってjavascriptのapiドキュメントを作ってみたメモ

Last updated at Posted at 2017-04-04

はじめに

気になっていたドキュメント作成ツールを試してみた。

作って比較した感想は以下。

  • sphinx:かなり奇麗なドキュメントを作成してくれる。rstは不馴れなのでmarkdown
  • jsdoc: 寂しい。簡単
  • jsdoc-minami: jsdocに少しの手間で見た目がかなり良くなる。es5が混じるならこれかな。
  • esdoc: es6でクラスを作るならこれがきれい。カバレッジがデフォルトなのもよさそう。jsdocほどの自由さはないので、古い記法が混じったりすると使いにくいかも。
  • jsdoc-sphinx: そこそこの見た目とsphinxの統一感。rstファイルが出力されるので最後に編集できる。テンプレートが英語なので日本語で使うなら書き換えたほうがよいかも。
  • sphinx-js: 見た目は一番好み。sphinxのautodocをjsで使えるようにしたもの。sphinx-apidocがjavascriptのソースで使えるならこれを選んでいた。索引を自動生成してくれるのも嬉しい。何か方法ないかなあ。
  • typedoc: typedocは以前作成したソースがあったので、比較用に入れてみた。

作成したページのサンプル - github.io

動作環境

  • windows10
  • vagrant1.9.2
  • virtualbox5.1
  • ubuntu-16.04
  • docker17.03
  • docker-compose1.11.2

ディレクトリ構成

- project
  - bin # dockerのコマンド実行用のシェル
    - generate.sh        # ドキュメント作成
  - docker-compose.yml # docker設定ファイル
  - documentation_generator
    - esdoc
      - .esdoc.json # esdocの設定ファイル
    - jsdoc
      - .jsdoc.json # jsdocの設定ファイル
      - README.md   # jsdocで作成したドキュメントのindex用
    - sphinx
      - source
        + _static   # sphinxの静的ファイル格納用
        + _template # sphinxのテンプレート格納用
      - build.sh # 起動用
      - Makefile # 起動用
    - sphinx-js
      - source
        - conf.py # sphinxの設定（sphinx-js用)
    - Dockerfile # dockerファイル
  - typedoc
    - Dockerfile # typedoc用dockerファイル
    - package.json  # npmスクリプトを記述したファイル
    - tsconfig.json # typescript用設定
  - docs # sphinxで出力するドキュメントのソース
    - contents 
      + jsdoc-sphinx # jsdoc-sphinxから出力されるファイル格納用ディレクトリ
      + sphinx-js    # sphinx-jsを試すために作成したファイルをいれたディレクトリ
      - esdoc.md     # sphinxのマークダウンテスト用
      - jsdoc.md
      - sphinx.md
    - index.rst # sphinxの最初のインデックス用
  - src # apiを作成したいソースファイル
    - code.js
    - esdoc
      - MyClass.js
    - typedoc
      - es6.ts
  - dist # 作成されたドキュメント格納用ディレクトリ
    - docs
      - api
        + esdoc # esdocで作成されたapiドキュメント
        + jsdoc # jsdocで作成されたapiドキュメント
        + minami # jsdocのminamiテンプレートで作成されたapiドキュメント
        + typedo # typedocで作成されたapiドキュメント
      + doctrees # sphinxのドキュメントツリー
      + html # sphinxが作成するドキュメント

ファイル

docker-compose.yml
version: '2'
services:
  documentation_generator:
    build: ./documentation_generator
    volumes:
      # sphinxのMakefile
      - ./documentation_generator/sphinx/Makefile:/root/Makefile
      # sphinxの起動ファイル
      - ./documentation_generator/sphinx/build.sh:/root/build.sh
      # shpinxの生成するHTMLのテンプレート
      - ./documentation_generator/sphinx/source/_templates:/root/source/_templates
      # shpinxの静的HTMLファイル
      - ./documentation_generator/sphinx/source/_templates:/root/source/_static
      # sphinx-jsのコンフィグファイル
      - ./documentation_generator/sphinx-js/source/conf.py:/root/source/conf.py
      # esdocの設定ファイル
      - ./documentation_generator/esdoc/.esdoc.json:/root/.esdoc.json

      # jsdocの設定ファイル
      - ./documentation_generator/jsdoc/.jsdoc.json:/root/.jsdoc.json

      # jsdocのREADMEファイル
      - ./documentation_generator/jsdoc/README.md:/root/README.md
      # sphinxでコンパイルするときの開始ファイル
      - ./docs/index.rst:/root/source/index.rst
      # ドキュメントのフォルダ
      - ./docs/contents:/root/source/contents
      # ビルドされたファイルの格納ディレクトリ
      - ./dist/docs:/root/build
      # apiドキュメントを作成したいソースファイルの格納ディレクトリ
      - ./src:/root/src
  # typedoc
  documentation_generator_typedoc:
    build: ./typedoc
    volumes:
    # ビルドするソースファイル
    - ./src:/my_typedoc/src
    # ビルドファイルの出力先
    - ./dist/docs/api/typedoc:/my_typedoc/dist
    # コンテナ上のpackage.jsonを上書き
    - ./typedoc/package.json:/my_typedoc/package.json
    # typescriptの設定ファイル
    - ./typedoc/tsconfig.json:/my_webpack/tsconfig.json
document_genarator/Dockerfile
FROM python:3.6

# curlをインストール
RUN apt-get install -y curl

# node.jsをインストール
RUN curl -sL https://deb.nodesource.com/setup_6.x | bash -
RUN apt-get install -y nodejs

# gitをインストール
RUN apt-get install -y git

# jsdocをインストール
RUN npm install -g jsdoc

# sphinxをインストール
RUN pip install git+https://github.com/sphinx-doc/sphinx@stable

# sphinxのマークダウン記法を可能にするプラグイン
RUN pip install recommonmark 

# esdocのインストール
RUN npm install -g esdoc

# 作業ディレクトリに移動
WORKDIR /root

# jsdocテンプレートminamiのインストール
RUN npm init -y
RUN npm install --save-dev minami

# jsdocテンプレートjsdoc-sphinxのインストール
RUN npm install jsdoc-sphinx

# sphinx-jsのインストール
RUN pip install 'sphinx-js>=1.5,<2.0'

CMD ["/bin/sh", "/root/build.sh"]
document_genarator/sphinx/build.sh
cd /root && make html
document_genarator/sphinx/Makefile
# Makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS    =
SPHINXBUILD   = sphinx-build
PAPER         =
BUILDDIR      = build

# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif

# Internal variables.
ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source

.PHONY: html
html:
    $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
    @echo
    @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
document_genarator/sphinx-js/source/conf.py
import sys
import os
import shlex

# マークダウンが使用できるように設定
import recommonmark
from recommonmark.parser import CommonMarkParser
source_parsers = {
    '.md': CommonMarkParser
}
source_suffix = ['.rst', '.md']

# sphinx-jsを使用するための設定
js_source_path = '/root/src'        # jsソースのパス
jsdoc_config_path = './.jsdoc.json' # jsdocのconfigファイルのパス
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_js'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The master toctree document.
master_doc = 'index'

# Usually you set "language" from the command line for these cases.
language = 'ja'
# directories to ignore when looking for source files.
exclude_patterns = []

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False

# -- Options for HTML output ----------------------------------------------

# a list of builtin themes.
html_theme = 'alabaster'
html_static_path = ['_static']
document_genarator/esdoc/.esdoc.json
{
  "source": "/root/src",
  "destination": "/root/build/api/esdoc"
}
document_genarator/jsdoc/.jsdoc.json
{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc"]
    },
    "source": {
        "include": ["/root/src", "package.json", "README.md"],
        "includePattern": ".js$",
        "excludePattern": "(node_modules/|docs)"
    },
    "plugins": [
        "plugins/markdown"
    ],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": true,
        "useLongnameInNav": false
    },
    "opts": {
        "destination": "./build/api/minami",
        "encoding": "utf8",
        "private": true,
        "recurse": true,
        "template": "./node_modules/minami"
    }
}
typedoc/Dockerfile
# docker-hubからnode入りコンテナを取得
# https://hub.docker.com/_/node/
FROM node

# コンテナ上の作業ディレクトリ作成
WORKDIR /my_typedoc

# 後で確認出来るようにpackage.jsonを作成
RUN npm init -y

# typescript doc
RUN npm i --save-dev typedoc

# typescript
RUN npm i --save-dev typescript
typedoc/package.json
{
  "scripts": {
    "typedoc": "typedoc",
    "doc": "npm run typedoc -- --target es6 --moduleResolution node --ignoreCompilerErrors --out ./dist/ ./src/"
  }
}
typedoc/tsconfig.json
{
    "compilerOptions": {
        "module": "commonjs",
        "target": "es6",
        "noImplicitAny": false,
        "sourceMap": false
    }
}
docs/index.rst
ドキュメントジェネレータテスト
=======================================

Contents:

.. toctree::
   :maxdepth: 1

   contents/esdoc
   contents/jsdoc
   contents/sphinx
   contents/jsdoc-sphinx/index
   contents/sphinx-js/index

Apiドキュメント
==================

* `Jsdoc APIドキュメント <../api/jsdoc/index.html>`_ 
* `Jsdoc - minami APIドキュメント <../api/minami/root/1.0.0/index.html>`_ 
* `Esdoc APIドキュメント <../api/esdoc/index.html>`_ 
* `Typedoc APIドキュメント <../api/typedoc/index.html>`_ 

索引
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
bin/generate.sh
#!/bin/bash

# このシェルスクリプトのディレクトリの絶対パスを取得。
bin_dir=$(cd $(dirname $0) && pwd)

# jsdoc作成
cd $bin_dir/../ && docker-compose run documentation_generator jsdoc -d /root/build/api/jsdoc /root/src -r

# jsdoc作成 - minamiテンプレート
cd $bin_dir/../ && docker-compose run documentation_generator jsdoc -c /root/.jsdoc.json

# jsdoc作成 - jsdoc-sphinxテンプレート
cd $bin_dir/../ && docker-compose run documentation_generator jsdoc -t node_modules/jsdoc-sphinx/template -d /root/source/contents/jsdoc-sphinx /root/src -r

# esdoc作成
cd $bin_dir/../ && docker-compose run documentation_generator esdoc -c /root/.esdoc.json

# typedoc作成
cd $bin_dir/../ && docker-compose run documentation_generator_typedoc npm run doc

# sphinxドキュメント作成
cd $bin_dir/../ && docker-compose run documentation_generator make html

実行

generate.shでドキュメント作成後、dist/docs/html/index.htmlをひらいて確認できる。

githubソース

今回試したソースは以下。

github

参考

SphinxドキュメントをDockerでビルドする
業務での利用事例Add Star
PythonプロジェクトのドキュメントをSphinxで作成する
プロジェクトを作る
逆引き辞典
ドメイン
sphinx-js
conf.py
extension
okikata
拡張
study 日本語解説
jsdoc-sphinx
github - jsdoc
eclipse - jsdoc
use jsdoc
expressでのjsdoc
jsdocをbootstrapできれいに整形する
JSDoc使い方メモ
wordpress js規約日本語訳
Sphinx でドキュメントを作成して GitHub Pages で公開するまで
Sphinx-Users.jp — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会

9
13
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
9
13