Sphinxを使ってPythonパッケージのドキュメントを作る

このページでは、 Sphinx を使ってユーザー向けのパッケージのドキュメントをビルドする方法について説明します。 Sphinxは科学的なPythonのエコシステムで現在最もよく使われているツールですが、Pythonのパッケージングエコシステムで人気を集めている mkdocs のような、ドキュメントをビルドするための他のツールを調べることも歓迎します。

Tip

私たちが気に入っているドキュメンテーションのウェブサイトの例:

• GeoPandas

  • ランディングページを作成するために最初にご覧ください

• verde

  • verdeランディングページのコードを見る - rstファイル

• ランディングページのmyST例をご覧になりたい方は、こちらのドキュメントをご覧ください

Sphinx - 静的サイトジェネレーター

Sphinxは スタティックサイトジェネレーター です。 静的サイトジェネレータとは、テンプレートのセットに基づいて、ウェブサイトのhtmlを作成するツールです。 htmlファイルは「静的」に提供されるため、その場でファイルを生成したり変更したりすることはありません。

SphinxはPythonで書かれています。

Sphinxサイトは拡張機能やテーマを使ってカスタマイズできます

The functionality of Sphinx can be extended using extensions and themes. A few examples include:

• ドキュメントテーマを適用して、美しいドキュメントを素早く作成することができます。

• autodocエクステンションを使って、パッケージの関数やクラス(パッケージのAPI)のドキュメントをコードのdocstringから自動的に作成する ことができます。

• doctestエクステンションを使って、docstringのコード例を 実行してテストする ことができます。

• While Sphinx natively supports the rST syntax, you can add custom syntax parsers to support easier-to-write syntax using tools such as the MyST parser.

よく使われるSphinxのテーマ

あなたは好きなSphinxテーマを自由に使うことができます。 しかし、Pythonの科学コミュニティで最もよく使われているSphinxのテーマは次のようなものです:

• pydata-sphinx-theme

• sphinx-book-theme

• furo

Tip

この本はSphinxと furo というテーマを使って作られています。