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

Comments

1. 

   @TEISHOTOKU-P

   Questioner

   more_horiz

   回答ありがとうございます。
   somewhere/elseには自分のチェックしたいディレクトリを実際に記述するということですね。ありがとうございます。
   
   ＞JavaScript から Sphinx ドキュメントの生成を実行するという意味でしょうか。それとも、 Python や Sphinx に依存せずに JavaScript だけで完結するドキュメントツールはあるか、ということでしょうか。
   
   前者になります。sphinx-jsを用いて、sphinx apidocでpythonファイルのdocstringを読み取るように、JSファイルのjsdocを読み取り、ドキュメントを自動生成したいということです。
2. 

   @uasi

   more_horiz

   rST に .. js:autofunction:: someFunction と書けば JS のソースから someFunction の JSDoc を取り込んでドキュメントを生成してくれるようです。
3. 

   @TEISHOTOKU-P

   Questioner

   more_horiz

   お返事ありがとうございます。
   .. 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()関数らしきものはありませんでしたが、どこにあるのでしょうか。
4. 

   @uasi

   more_horiz

   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 が拡張機能をロードするとき自動的に呼び出すものなので気にする必要はありません。
5. 

   @TEISHOTOKU-P

   Questioner

   more_horiz

   本当にありがとうございます。
   pipでインストールしたところ、setup関数エラーが取れ、jsdocを-gでインストールするよう勧められました。
   
   確かにconf.pyのextensionsに'sphinx-js'で通していました。
   
   現在、下記の点を調査中です。ですが、まだ調査を始めたばかりなのでまずは自力で調査してみます。またわからなくなってしまった場合、また質問させていただきたいです。この度は本当にありがとうございました。
   
   「jsdocをグローバルではなくローカルでインストールしてmake htmlコマンドを実行することは可能なのか」
6. 

   @uasi

   more_horiz

   仕組みがややこしいので回答してしまいますと、
   
   > jsdocをグローバルではなくローカルでインストールしてmake htmlコマンドを実行することは可能なのか
   
   可能です。 JSDoc をローカルにインストールすると node_modules/.bin に jsdoc コマンドが入るのでそこに PATH を通してください。以下のように実行すればいけます（カレントディレクトリの一段上に node_modules がある場合）。
   
   PATH=$PWD/../node_modules/.bin:$PATH make html
7. 

   @TEISHOTOKU-P

   Questioner

   more_horiz

   ありがとうございます。
   ```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
   ```
8. 

   @uasi

   more_horiz

   jsdoc が何かのディレクトリをファイルとして開こうとして失敗しているようです。 conf.py で jsdoc_config_path をディレクトリに指定していませんか？　他の可能性もあると思いますが、実際の設定を見ないとこれ以上は分かりません。
9. 

   @TEISHOTOKU-P

   Questioner

   more_horiz

   お返事ありがとうございます。
   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
   ```
10. 

    @uasi

    more_horiz

    > Rule 'name' didn't match at '.' (line 1, column 22).
    
    メソッド名なり変数名なりを書くべき場所（1行目の22文字目）にピリオドがあるようです。手元で以下のコメントを書いてみたところ同じエラーが出ました。
    
    /** @method . */
    function func() { }
    
    コメントの書き方を間違えていないか確認してください。
11. 

    @uasi

    more_horiz

    jsdoc_config_path はディレクトリではなく設定ファイルのパスを指定すれば動きます。
12. 

    @TEISHOTOKU-P

    Questioner

    more_horiz

    お返事ありがとうございます。
    どうやら```Rule 'name' didn't match at '.' (line 1, column 22).```の指摘箇所は指定したjsファイルではないようです。
    ドキュメント生成したいすべてのjsファイルの１行目をチェックしましたが、'.’は見当たりませんでした。
    また、jsdoc_config_pathに指定する設定ファイルが存在せず、jsdocフォルダ内にあった、conf.json.EXAMPLEのソースをそのままコピペし、jsdoc.jsonを作成しました。それをjsdoc_config_pathに指定して実行してみましたが、同じエラー結果でした。
13. 

    @uasi

    more_horiz

    改めて確認したところ、 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 ディレクティブにミスがある可能性が考えられます。
14. 

    @TEISHOTOKU-P

    Questioner

    more_horiz

    お返事ありがとうございます。
    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ファイルの関数を指定して実行してみましたが、上記のエラー文の指摘箇所が、指定した関数に入れ替わっただけで出力されました。
15. 

    @uasi

    more_horiz

    指定した名前の関数が見つからないかその関数に JSDoc コメントが書かれていないようです。 js_source_path の指定が正しいか、 関数名は合っているか、 JSDoc コメントが書かれていて形式が正しいかを確認してください。
    
    js_source_path は conf.py がある場所からの相対パスでディレクトリ名を指定します。
    
    JSDoc コメントは関数の直前の行に /** 〜 */ で囲って書きます。開きマーカー /** のアスタリスクは1個でも3個以上でもだめでちょうど2個必要です。
16. 

    @uasi

    more_horiz

    js_source_path の指定は合っていそうですね。指定先に JS ファイルが見つからないなら Sphinx error: jsdoc found no JS files in the directories とエラーが出るはずなので。
17. 

    @TEISHOTOKU-P

    Questioner

    more_horiz

    お返事ありがとうございます。
    
    試しに、rstで指定した関数を持ったjsファイルに対しjsdocを実行した結果、
    ドキュメントが生成されていたので、コメント、関数に問題はなさそうです。
18. 

    @uasi

    more_horiz

    対象の関数を定義した JS ファイルが js_source_path 指定先のサブディレクトリにあったりしないでしょうか。仮に js_source_path = '../src' と指定したとすると、 ../src/a.js と ../src/b.js は読み込まれますが ../src/xyz/c.js は読み込まれません。
19. 

    @TEISHOTOKU-P

    Questioner

    more_horiz

    お返事ありがとうございます。
    パス再度確認しましたが、正しいパスでした。
    '../src'内にある複数のjsファイルを指定したい関数を持ったファイル１つのみにしてコマンドを実行してみることもしましたが同じエラーが表示されてしまいます。
    
20. 

    @uasi

    more_horiz

    なるほど。これ以上は実際のコードを見てみないと調査は難しそうです。
    
    sphinx-js が正常に動く最低限のサンプルコードを作りましたので、よろしければご参照ください。 https://gitlab.com/uasi/20210413-sphinx-js-docs/
    git clone して npm install && npm run build すればドキュメントが生成されるようになっています。
21. 

    @TEISHOTOKU-P

    Questioner

    more_horiz

    本当にありがとうございます。
    
    参考にさせて頂き色々と試してみた結果、私の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でドキュメントを作成することができました。
    本当にありがとうございます。