Liquidsのロゴ Liquids

0

MkDocsによるドキュメント作成【Python】

Python

Pythonプロジェクトでドキュメントを自動生成する選択肢として、Sphinxなどがありますが、このWikiではMkDocsを用いてドキュメントを自動生成する方法を紹介します。

MkDocsではPythonのdocstringからドキュメントを生成することが可能です。

また、MkDocsを用いてドキュメントが作られているサイトとして

  • FastAPI
  • Pydantic

があります。

pip install mkdocs

mkdocsをインストールすると、mkdocsコマンドが使えるようになります。

mkdocs -V
# mkdocs, version 1.5.3

次に、MkDocsのテーマとしてmaterialをインストールします。なくてもMkDocsは使えますが、見た目が良いので入れておきましょう。FastAPIやPydanticでも使用されているテーマです。

pip install mkdocs-material

最後にdocstringでドキュメント生成ができるようにするプラグインをインストールします。

pip install 'mkdocstrings[python]'

mkdocs.yamlというMkDocsの設定ファイルを作ります。

特にこだわりがなければプロジェクトのルートにおけば良いと思います。

site_name: ドキュメントサイト名

theme:
  name: "material"
  
plugins:
  - search
  - mkdocstrings

mkdocs.yamlと同じ階層にdocsフォルダを作成します。
そして、docsフォルダ内にドキュメントを生成する元になるMarkdownを書いていきます。

# Doc Example

::: src.example.example_func

ここに書いたMarkdownはドキュメントに反映され、::: 対象はdocstringを用いたドキュメント生成に必要なものです。

docstringを用いたドキュメント生成の対象は パス + 名前 (Pythonの拡張子は入りません)で表します。
名前というのは関数やクラスの名前です。

example_funcは以下で作ってみます。

def example_func(num1: int, num2: int) -> int:
    '''
    引き算を行う関数。MkDocs用の動作確認用に作りました。

    Args:
        num1 (int): 引かれる値
        num2 (int): 引く値

    Returns:
        int: 引き算の結果
    '''

    return num1 - num2

docstringの書き方は次の記事が参考になります。

これまでのSTEPが完了していればドキュメントを生成できるはずです。
コマンドでドキュメントを起動してみましょう。

mkdocs serve

Liquidsのロゴ Liquids

Liquidsは誰でも投稿・編集ができる技術Wikiコミュニティ📝です。

あなたもLiquidsで技術Wikiを
書いてみませんか?