nikkie-ftnextの日記

イベントレポートや読書メモを発信

sphinx.ext.autodocでdocstringを元に作ったHTMLの中の外部リンクも、sphinx-new-tab-link を使ってブラウザの新しいタブで開けることを確認しました

Sphinx

はじめに

聞いて聞いて！ nikkieです。

ドキュメント変換ツールSphinxのautodoc拡張を使うと、Pythonファイルからドキュメント（HTMLやPDFなどなど）を作れます。
HTMLでドキュメントを作るときに、このautodoc拡張と、私が先日リリースしたライブラリsphinx-new-tab-linkが一緒に使えるのか検証しました。
11/27のSphinx+翻訳 Hack-a-thon 2022.11で取り組みました。

目次

結論：autodocとsphinx-new-tab-linkは一緒に使えます！

百聞は一見に如かず、sphinx-new-tab-linkのAPIドキュメントを実際にご覧ください。

sphinx-new-tab-linkでは、実装の参考にしたStackOverflowの回答をdocstringに書いています1。

class NewTabLinkHTMLTranslator(HTMLTranslator):
    """...

    ref: https://stackoverflow.com/a/67153583
    """

autodoc拡張によって、このdocstringを元に作られたドキュメントが上記ページです。
APIドキュメントでは、StackOverflowのリンクがブラウザの新しいタブで開きます！🙌

autodocとsphinx-new-tab-linkを一緒に使う設定例

conf.py2

import os
import sys

sys.path.insert(0, os.path.abspath("相対パスで指定"))

extensions = [
    "sphinx.ext.autodoc",
    "sphinx_new_tab_link",
]

sphinx-new-tab-linkのAPIドキュメントの裏側（ドッグフーディング！）

上記のAPIドキュメントの元はapi.rstです。

API
===

.. automodule:: sphinx_new_tab_link
    :members:

sphinx_new_tab_linkモジュール中のdocstringを持つメンバーからドキュメントを作るよう指定しています。

そもそもautodocとは？

Sphinxがインクルードしている拡張の一つ（sphinx.ext.autodoc）です。

この拡張については、2020年6月のみんなのPython勉強会（a.k.a stapy）「Python製ドキュメント生成ツールSphinx丸わかり」で、tk0miyaさんのトークで聞いたとおぼろげながら覚えていました。

sphinx-new-tab-linkを公開してから、reSTのURLの記法には様々な種類があることに気付いて、サポートできていることを確認しています3。
確認した後、ふと「docstringから作ったドキュメントに含まれるURLも、ひょっとしてサポートできているんじゃないかな」と思ったのです。
そして、過去のstapyのSphinx回の資料をたどり、autodocを素振りしてから、一緒に使えることを確認しました。

sphinx.ext.autodoc素振り

「Sphinx で Python プログラムのドキュメントを書こう」（みんなのPython勉強会 #58）

（55:00過ぎからです）

発表の例を写経

まずSphinxプロジェクトを用意します。
まっさらな環境でsphinx-quickstartをしてもいいと思います。
私は横着をしてsphinx-new-tab-linkのドキュメント環境（docsディレクトリ以下）を使いました。

関係するファイルに絞って表したディレクトリツリーはこんな感じです。

.
├── conf.py  # sphinx-quickstartで作成済み。**編集する**
├── example.py  # 新規作成
├── index.rst  # sphinx-quickstartで作成済み。**編集する**
├── Makefile  # sphinx-quickstartで作成済み
└── make.bat  # sphinx-quickstartで作成済み

ドキュメントにするPythonファイルexample.pyを用意します。

class Math:
    """数値計算用のクラスです。"""

    def add(self, x: int, y: int) -> int:
        """指定した2つの数値を加算します。

        :param x: 数値1
        :param y: 数値2
        """
        return x + y


class SuperMath:
    #: 円周率
    PI = 3.14

    def mul(self, x, y):
        return x * y

conf.pyは2箇所設定を加えます。

  1. ロードバスの追加
  2. extensionsに追加してautodocを有効化
import os
import sys
sys.path.insert(0, os.path.abspath("."))  # conf.py と同じディレクトリにある example.py をロードできるようにする

extensions = [
    "sphinx.ext.autodoc",
]

autodoc拡張が提供するディレクティブをindex.rstの中に書きました。

.. automodule:: example
   :members:
   :undoc-members:

example.py全体からドキュメントを作っています。
docstringがないメンバーであってもドキュメントに含める指定です。

以上で完了！
make htmlすると、example.pyのドキュメントができあがります！

Future works（素振りを通して存在を知った拡張たち）

stapyの発表資料にもありましたが、sphinx.ext.intersphinxは気になりますね。
型ヒントのintをPython公式ドキュメントへのリンクにしていました。

また、sphinx.ext.viewcodeとsphinx.ext.linkcodeも気になります。

ライブラリのドキュメントで見たことがあるのですが、sourceへ飛べるドキュメントの秘密は前者なのかな？

今回はautodoc自体が初めてだったのでtoo muchにならないようにセーブしましたが、このあたりも触ってみたいところです。

終わりに

sphinx.ext.autodocを初めて触りました。
いや〜、docstringを元にしたドキュメントが作れるのはとても便利ですね4。

そして、自作ライブラリsphinx-new-tab-linkと合わせて使えることも確認しました！
もしかしてautodoc使っているドキュメントは簡単にsphinx-new-tab-linkの恩恵にもあずかれる、ｯﾃｺﾄ…?
「sphinx-new-tab-link、ライブラリのドキュメントで広く使っていただけそう」と可能性しか感じません！（普及したらsphinx.extシリーズの中に入りうるのでは…❣️　←親バカ）

「この記事でsphinx-new-tab-linkを知ったよ」という方、ぜひぜひ試していただき、ちょっとしたことでもかまいませんので、（伸びしろだけでなくぜひぜひよい点も）フィードバックをお寄せください！

私、アスタリスクが好きなんですが、スター🌟をいただいても嬉しいです！

P.S. docstringのスタイルについて

素振りを通して存在を知った拡張はもう1つあります。
その名はnapoleon。

docstringのスタイルは3つあります。

  • reStructuredText (reST)
  • NumPy
  • Google

autodocはreSTスタイルを前提にしていましたが、reSTスタイルでなくてもnapoleonを使えばautodocでドキュメントに出力できるようです。

今回sphinx-new-tab-linkのAPIドキュメントを作るにあたってはreSTスタイルを採用しました。
理由は（新しいものがtoo muchにならないようにするのに加えて）PyCon JP 2019の「チームメイトのためにdocstringを書こう」でreSTスタイル + 型ヒントが紹介され（スライド23）、私にはこれがしっくり来ていたためです。

  1. https://github.com/ftnext/sphinx-new-tab-link/blob/v0.1.1/sphinx_new_tab_link/__init__.py#L4-L8↩
  2. https://github.com/ftnext/sphinx-new-tab-link/blob/f2ae70d92c2d9ad390381da4c8677687ec634ec3/docs/conf.py↩
  3. reStructuredTextとリンクを作るマークアップ（全部一緒だと思っていたのですが、細かい意味の違いがあった…だと…） - nikkie-ftnextの日記↩
  4. コラボレータを始めたSpeechRecognitionはdocstringとドキュメント用reSTファイルで二重管理になっている（一部はreSTが古くなってしまっている）ので、autodocさん、助けてください！🙏↩