Sphinx(スフィンクス)の使い方

ドキュメント作成ツール

1.Sphinxの概要
 Sphinxは、Pythonで書かれたドキュメント生成ツールであり、特にソフトウェアプロジェクトのドキュメント作成に広く使用されています。主に次のような特徴があります。
(1)リッチなテキストフォーマット
 reStructuredText(reST)という軽量マークアップ言語を使用してドキュメントを記述します。reSTはシンプルでありながら強力で、ヘッディング、リスト、リンク、コードブロックなどを簡単に作成できます。

(2)自動リンク生成
 ソースコード内のクラス、関数、モジュールなどへのリンクを自動的に生成します。これにより、ドキュメントのナビゲーションが容易になります。

(3)複数の出力形式
 HTML、LaTeX(PDF)、EPUB、manページ、Texinfo、Markdownなど、さまざまな形式のドキュメントを生成できます。

(4)拡張性
 拡張機能を利用することで、機能を追加したりカスタマイズしたりできます。多くのプラグインがコミュニティによって開発されています。

(5)テーマのカスタマイズ
 見た目をカスタマイズするためのテーマを選択できます。また、独自のテーマを作成することも可能です。

(6)コードのサポート:
 ドキュメント内にコードブロックを含めることができ、コードのシンタックスハイライトもサポートしています。

 Sphinxは主にPythonのプロジェクトで使われますが、Python以外のプロジェクトでも利用可能です。ドキュメントの生成と管理を容易にし、高品質なドキュメントを提供するためのツールとして非常に有用です。

 公式ドキュメントやチュートリアルを参照することで、Sphinxの設定方法や使用方法について詳細を学ぶことができます。

・Sphinx公式サイト
https://www.sphinx-doc.org/ja/master/index.html

・Sphinx-Users.jp Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
https://sphinx-users.jp/

2.Sphinxのセットアップ
(1)Sphinxのインストール
 $ pip install sphinx

(2)フロー図のためのGraphvizのインストール
 $ pip install sphinxcontrib-plantuml

3.Sphinxの使い方
(1)Sphinxプロジェクトの作成
 $ sphinx-quickstart
 souceフォルダが作成されます。

(2)ドキュメントの作成
 プロジェクトフォルダのsourceディレクトリ内にindex.rstファイルがあります。このファイルに文章、表、フロー図を追加します。

.. My Documentation Master file

Welcome to My Documentation!
============================

This is an example document created with Sphinx.

Contents:

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

Introduction
============

This document demonstrates how to include text, tables, and flowcharts.

Text Section
------------

Here is some example text. You can write your documentation in reStructuredText.

Table Section
-------------

Here is an example table:

.. list-table:: Example Table
   :header-rows: 1

   * - Header 1
     - Header 2
   * - Row 1, Column 1
     - Row 1, Column 2
   * - Row 2, Column 1
     - Row 2, Column 2

Flowchart Section
-----------------

Here is an example flowchart:

.. graphviz::

   digraph flowchart {
       A -> B;
       B -> C;
       C -> D;
   }

(3)conf.pyの設定
 source/conf.pyファイルを開き、以下の行を追加してgraphviz拡張機能を有効にします。

(4)ドキュメントのビルド
 以下のコマンドでHTMLドキュメントをビルドします。
 $ make html

(5)Ubuntuのブラウザで表示する
  
  /home/mlearn/build/html/index.html

タイトルとURLをコピーしました