Sphinx を使用したプロジェクト文書化の最初のステップ

HTML ドキュメントの作成

sphinx-quickstart が作成した index.rst ファイルには既にいくつかのコンテンツが含まれており、HTML ドキュメントのトップページとしてレンダリングされます。これは、強力なマークアップ言語である reStructuredText で記述されています。

ファイルを次のように変更します

docs/source/index.rst
Welcome to Lumache's documentation!
===================================

**Lumache** (/lu'make/) is a Python library for cooks and food lovers that
creates recipes mixing random ingredients.  It pulls data from the `Open Food
Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
*intuitive* API.

.. note::

   This project is under active development.

これにより、reStructuredText 構文のいくつかの機能が示されます。これには以下が含まれます。

  • 下線に === を使用したセクションヘッダー、

  • 2 つの インラインマークアップ の例：**strong emphasis**（通常は太字）と *emphasis*（通常は斜体）、

  • インライン外部リンク、

  • および note アドモニション（利用可能な ディレクティブ の 1 つ）

新しいコンテンツでレンダリングするには、前述のように sphinx-build コマンドを使用するか、次の便宜的なスクリプトを利用できます。

(.venv) $ cd docs
(.venv) $ make html

このコマンドを実行した後、index.html に新しい変更が反映されていることがわかります！

その他の形式でのドキュメントの作成

Sphinx は、HTML 以外にも、PDF、EPUB、その他多数 の形式をサポートしています。たとえば、EPUB 形式でドキュメントを作成するには、docs ディレクトリから次のコマンドを実行します。

(.venv) $ make epub

その後、電子書籍に対応するファイルが docs/build/epub/ の下に表示されます。Calibre などの EPUB 対応電子書籍ビューアで Lumache.epub を開くか、Web ブラウザで index.xhtml をプレビューできます。

注記

可能な出力形式の完全なリストと、その他の便利なコマンドをすばやく表示するには、make help を実行します。

各出力形式には、EPUB を含む 、調整できる特定の設定オプションがあります。たとえば、epub_show_urls のデフォルト値は inline であり、デフォルトでは URL が対応するリンクの直後に括弧で表示されます。 conf.py の最後に次のコードを追加することで、この動作を変更できます。

# EPUB options
epub_show_urls = 'footnote'

この設定値を使用して、もう一度 make epub を実行すると、URL が脚注として表示されるようになり、テキストが散らからなくなります。素晴らしい！Sphinx をカスタマイズするその他の方法 を探るために読み進めてください。

注記

Sphinx を使用して PDF を生成するには、sphinx.builders.latex.LaTeXBuilder のドキュメントで説明されているように、システムに動作する LaTeX インストールがあることを前提として、make latexpdf を実行します。これは完全に実行可能ですが、このようなインストールは多くの場合大きく、一般的に LaTeX は場合によっては慎重な設定が必要であるため、このチュートリアルでは PDF の生成は範囲外です。