@TEISHOTOKU-P (低所得 -P)posted at 2021-04-06

Sphinx-jsでドキュメントを自動生成できた方いますか？

Q&A

解決したいこと

Sphinx-jsでドキュメントを自動生成したい。

sphinx-quickstartで生成されたindex.rst

.. test_doc documentation master file, created by
   sphinx-quickstart on Tue Apr  6 15:38:21 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to test_doc's documentation!
====================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

疑問

上記のファイルに以下のようなコードを追記することで、"make html"コマンドすれば、その選択した関数がドキュメントに載るようなのですが、そもそも指定する関数が記述されているJSファイルの紐づけはどこでされているのでしょうか。
.. js:autofunction:: someFunction
また、もっと下記のPythonのドキュメント自動生成コマンドのようにJavaScriptでも簡単に自動生成できるコマンドはないのでしょうか。
sphinx apidoc -f -o hogehoge.py

1Answer

@uasi posted at 2021-04-06

そもそも指定する関数が記述されているJSファイルの紐づけはどこでされているのでしょうか。

特に設定しなければ ../ にあるすべての JS ファイルから指定された名前の関数を探索します。現在のディレクトリが docs のようなドキュメントを入れるディレクトリだとして、その一段上にソースコードがある構造を仮定しているようです。探索先を変えるには conf.py に js_source_path = '../somewhere/else' のように設定します。

また、もっと下記のPythonのドキュメント自動生成コマンドのようにJavaScriptでも簡単に自動生成できるコマンドはないのでしょうか。

JavaScript から Sphinx ドキュメントの生成を実行するという意味でしょうか。それとも、 Python や Sphinx に依存せずに JavaScript だけで完結するドキュメントツールはあるか、ということでしょうか。

0Like

Comments

@TEISHOTOKU-P
Questioner
回答ありがとうございます。
somewhere/elseには自分のチェックしたいディレクトリを実際に記述するということですね。ありがとうございます。

＞JavaScript から Sphinx ドキュメントの生成を実行するという意味でしょうか。それとも、 Python や Sphinx に依存せずに JavaScript だけで完結するドキュメントツールはあるか、ということでしょうか。

前者になります。sphinx-jsを用いて、sphinx apidocでpythonファイルのdocstringを読み取るように、JSファイルのjsdocを読み取り、ドキュメントを自動生成したいということです。
@uasi
rST に .. js:autofunction:: someFunction と書けば JS のソースから someFunction の JSDoc を取り込んでドキュメントを生成してくれるようです。
@TEISHOTOKU-P
Questioner
お返事ありがとうございます。
.. js:autofunction:: someFunctionをrSTに記述し、make htmlを実行したのですが、
「WARNING: 拡張機能のセットアップ中 sphinx-js: 拡張 'sphinx-js'には setup()関数がありません。これは本当にSphinx拡張ですか？」
と表示され、結果、index.htmlを確認しても何も表示されていませんでした。
それで、setup()関数について調べたのですが、よく理解できませんでした。
npm i -D sphinxとnpm i -D sphinx-jsでインストールしましたが、どちらにもsetup()関数らしきものはありませんでしたが、どこにあるのでしょうか。
@uasi
npm の sphinx, sphinx-js はまったく無関係なパッケージです。必要なのは pip install sphinx sphinx-js と npm install -g jsdoc です。

> WARNING: 拡張機能のセットアップ中 sphinx-js: 拡張 'sphinx-js'には setup()関数がありません。これは本当にSphinx拡張ですか？

conf.py の設定で extensions = ['sphinx-js'] としていませんか？正しくは extensions = ['sphinx_js'] （区切りがハイフンではなくアンダースコア）です。 setup() 関数は sphinx_js モジュールの中で定義されています。 Sphinx が拡張機能をロードするとき自動的に呼び出すものなので気にする必要はありません。
@TEISHOTOKU-P
Questioner
本当にありがとうございます。
pipでインストールしたところ、setup関数エラーが取れ、jsdocを-gでインストールするよう勧められました。

確かにconf.pyのextensionsに'sphinx-js'で通していました。

現在、下記の点を調査中です。ですが、まだ調査を始めたばかりなのでまずは自力で調査してみます。またわからなくなってしまった場合、また質問させていただきたいです。この度は本当にありがとうございました。

「jsdocをグローバルではなくローカルでインストールしてmake htmlコマンドを実行することは可能なのか」
@uasi
仕組みがややこしいので回答してしまいますと、

> jsdocをグローバルではなくローカルでインストールしてmake htmlコマンドを実行することは可能なのか

可能です。 JSDoc をローカルにインストールすると node_modules/.bin に jsdoc コマンドが入るのでそこに PATH を通してください。以下のように実行すればいけます（カレントディレクトリの一段上に node_modules がある場合）。

PATH=$PWD/../node_modules/.bin:$PATH make html
@TEISHOTOKU-P
Questioner
ありがとうございます。
```PATH=$PWD/../node_modules/.bin:$PATH make html```を実行した結果以下のような出力をれてしまいました。ディレクトリの指定は正しいはずです。
conf.pyに指定したjs_source_pathも正しいことを確かめました。

```
EISDIR: illegal operation on a directory, read
Exiting JSDoc because an error occurred. See the previous log messages for details.

Sphinx error:
jsdoc found no JS files in the directories ['/home/user/sphinx-js/src/js']. Make sure js_source_path is set correctly in conf.py. It is also possible (though unlikely) that jsdoc emitted invalid JSON.
Makefile:20: recipe for target 'html' failed
make: *** [html] Error 2
```
@uasi
jsdoc が何かのディレクトリをファイルとして開こうとして失敗しているようです。 conf.py で jsdoc_config_path をディレクトリに指定していませんか？　他の可能性もあると思いますが、実際の設定を見ないとこれ以上は分かりません。
@TEISHOTOKU-P
Questioner
お返事ありがとうございます。
conf.pyにjsdoc_config_pathを指定していました。消した結果、上記エラーは生じなくなりました。ありがとうございます。

現在、新たなエラーに悩まされています。

```PATH=$PWD/../node_modules/.bin:$PATH make html```の実行結果…

```
$PATH=$PWD/../node_modules/.bin:$PATH make html
File "home/user/anaconda3/lib/python3.7/site-packages/parsimonious/expressions.py", line 127, in match
raise error
parsimonious.exceptions.ParserError: Rule 'name' didn't match at '.' (line 1, column 22).

完全なトレースバックを/tmp/sphinx-err-hogwz9l8.logに保存しました。問題を開発者に報告するときに添付してください。
次期バージョンでのエラーメッセージ改善のために、ユーザーエラーの場合にも報告してください。
バグ報告はこちらにお願いします <https://github.com/sphinx-doc/sphinx/issues> 。ご協力ありがとうございます！
Makefile:20: recipe for target 'html' failed
make: *** [html] Error 2
$

```
エラー文を調べてみるとヒットする記事は存在したのですが、載っていた解決策は前のバージョンのsphinx-jsのものであり、現在すでにそれが修正されたバージョンのsphinx-jsをインストールしているので解決にはなりませんでした。
その記事→https://github.com/mozilla/sphinx-js/issues/61

また、expressions.pyを確認してみたのですが、以下の部分でエラーを起こしています。

```
def match(self, text, pos=0):
"""Return the parse tree matching this expression at the given
position, not necessarily extending all the way to the end of ``text``.

Raise ``ParseError`` if there is no match there.
:arg pos: The index at which to start matching

"""
error = ParseError(text)
node = self.match_core(text, pos, {}, error)
if node is None:
raise error　　　←ココです
return node
```
@uasi
> Rule 'name' didn't match at '.' (line 1, column 22).

メソッド名なり変数名なりを書くべき場所（1行目の22文字目）にピリオドがあるようです。手元で以下のコメントを書いてみたところ同じエラーが出ました。

/** @method . */
function func() { }

コメントの書き方を間違えていないか確認してください。
@uasi
jsdoc_config_path はディレクトリではなく設定ファイルのパスを指定すれば動きます。
@TEISHOTOKU-P
Questioner
お返事ありがとうございます。
どうやら```Rule 'name' didn't match at '.' (line 1, column 22).```の指摘箇所は指定したjsファイルではないようです。
ドキュメント生成したいすべてのjsファイルの１行目をチェックしましたが、'.’は見当たりませんでした。
また、jsdoc_config_pathに指定する設定ファイルが存在せず、jsdocフォルダ内にあった、conf.json.EXAMPLEのソースをそのままコピペし、jsdoc.jsonを作成しました。それをjsdoc_config_pathに指定して実行してみましたが、同じエラー結果でした。
@uasi
改めて確認したところ、 rST ファイルに構文エラーがあっても同じエラーが出るようでした。また (line 1, column 22) はファイルの行番号ではなく、構文エラーのある行を起点とするようでした。たとえば rST ファイルの5行目に

.. js:autofunction:: hoge ..

と書くとエラーは Rule 'name' didn't match at '.' (line 1, column 7). になりました。（column 7 とは :: の次から数えて7文字目のことのようです）

よって、ドキュメントのどこかの js:autofunction ディレクティブにミスがある可能性が考えられます。
@TEISHOTOKU-P
Questioner
お返事ありがとうございます。
rstファイルに対する指摘文だと確認できました。ありがとうございます。

そこで、```.. js:autofunction :: someFunction ..```ではなく、最後の```..```を消してコマンドを実行した結果、
```
$ PATH=$PWD/../node_modules/.bin/:$PATH make html
Sphinx v3.5.3 を実行中
翻訳カタログをロードしています [ja]... 完了
出力先ディレクトリを作成しています... 完了
ビルド中 [mo]: 更新された 0 件のpoファイル
ビルド中 [html]: 更新された 1 件のソースファイル
環境データを更新中[新しい設定] 1 件追加, 0 件更新, 0 件削除
ソースを読み込み中...[100%] index
Sphinx error:
No documentation was found for object "someFunction" or any path ending with that.
Makefile:20: recipe for target 'html' failed
make: *** [html] Error 2
$
```
と表示されました。

そこで試しに、conf.py内のjs_source_pathに指定しているディレクトリ内のjsファイルの関数を指定して実行してみましたが、上記のエラー文の指摘箇所が、指定した関数に入れ替わっただけで出力されました。
@uasi
指定した名前の関数が見つからないかその関数に JSDoc コメントが書かれていないようです。 js_source_path の指定が正しいか、関数名は合っているか、 JSDoc コメントが書かれていて形式が正しいかを確認してください。

js_source_path は conf.py がある場所からの相対パスでディレクトリ名を指定します。

JSDoc コメントは関数の直前の行に /** 〜 */ で囲って書きます。開きマーカー /** のアスタリスクは1個でも3個以上でもだめでちょうど2個必要です。
@uasi
js_source_path の指定は合っていそうですね。指定先に JS ファイルが見つからないなら Sphinx error: jsdoc found no JS files in the directories とエラーが出るはずなので。
@TEISHOTOKU-P
Questioner
お返事ありがとうございます。

試しに、rstで指定した関数を持ったjsファイルに対しjsdocを実行した結果、
ドキュメントが生成されていたので、コメント、関数に問題はなさそうです。
@uasi
対象の関数を定義した JS ファイルが js_source_path 指定先のサブディレクトリにあったりしないでしょうか。仮に js_source_path = '../src' と指定したとすると、 ../src/a.js と ../src/b.js は読み込まれますが ../src/xyz/c.js は読み込まれません。
@TEISHOTOKU-P
Questioner
お返事ありがとうございます。
パス再度確認しましたが、正しいパスでした。
'../src'内にある複数のjsファイルを指定したい関数を持ったファイル１つのみにしてコマンドを実行してみることもしましたが同じエラーが表示されてしまいます。
@uasi
なるほど。これ以上は実際のコードを見てみないと調査は難しそうです。

sphinx-js が正常に動く最低限のサンプルコードを作りましたので、よろしければご参照ください。 https://gitlab.com/uasi/20210413-sphinx-js-docs/
git clone して npm install && npm run build すればドキュメントが生成されるようになっています。
@TEISHOTOKU-P
Questioner
本当にありがとうございます。

参考にさせて頂き色々と試してみた結果、私のjsファイルの書き方がsphinx-js的に良くなかったようです。usai様のソースコードで実行した結果、htmlが生成されました。
また先程、確認としてsphinx-jsのチュートリアルから持ってきたjsファイルのソースコードでmake htmlしてみた結果、htmlがきちんと作成される挙動を見せました。
```
$ PATH=$PWD/../node_modules/.bin/:$PATH make html
Sphinx v3.5.3 を実行中
翻訳カタログをロードしています [ja]... 完了
出力先ディレクトリを作成しています... 完了
ビルド中 [mo]: 更新された 0 件のpoファイル
ビルド中 [html]: 更新された 1 件のソースファイル
環境データを更新中[新しい設定] 1 件追加, 0 件更新, 0 件削除
ソースを読み込み中...[100%] index
更新されたファイルを探しています... 見つかりませんでした
環境データを保存中... 完了
整合性をチェック中... 完了
preparing documents... 完了
出力中...[100%] index
索引を生成中... genindex 完了
追加のページを出力中... search 完了
copying static files... 完了
extraファイルをコピー中... 完了
Japanese (code: ja) の検索インデックスを出力... 完了
オブジェクトインベントリを出力... 完了
ビルド成功.

HTMLページは_build/htmlにあります。
```
最初は、jsdoc単体でドキュメントを作成するときと同じソースでmake htmlを実行していましたが、そこが良くなかったのではないかと考えています。
Sphinx-js→jsdoc→jsソースだと、jsdocのルールが違うのかな？
と推測しました。

とにかく、sphinx-jsでドキュメントを作成することができました。
本当にありがとうございます。

Are you sure you want to delete the question?