Robot Framework + Libdocにて、自作ライブラリのドキュメントを作成する

この記事は 「Robot Framework Advent Calendar 2017 - Qiita」 の19日目の記事です。

Robot Framework Advent Calendar 2017の7日目でRobot Frameworkの自作ライブラリを作成しました。
Robot Frameworkのライブラリを自作する - メモ的な思考的な

その時は自作ライブラリにドキュメントを付けていませんでした。

今回は、Robot Frameworkに付属している Libdoc を使い、自作ライブラリのドキュメントを作成してみます。

　
目次

環境

• Python 3.6.3
• Robot Framework 3.0.2

　
なお、対象の自作ライブラリは、以下を拡張していきます。

MyLibrary.py

from robot.api import logger


class MyLibrary:
    def hello_world(self, name='foo'):
        logger.console(f'hello, world {name} !')

Libdocでドキュメントを生成する

Libdoc では、ソースコード中のコメントを元にドキュメントを作成します。

最初なので hello, world的にLibdocでドキュメントを生成してみます。

# ディレクトリ構成を確認する
$ tree libdoc_sample/
libdoc_sample/
└── MyLibrary.py

0 directories, 1 file

# MyLibrary.pyファイルがあるディレクトリへ移動する
$ cd libdoc_sample/

# ヘルプで実行方法を確認する
$ python -m robot.libdoc --help
robot.libdoc -- Robot Framework library documentation generator

Version:  3.0.2 (Python 3.6.3 on darwin)

Usage:  python -m robot.libdoc [options] library output_file
...

# robot.libdocを実行すると、ドキュメントのHTMLが生成される
$ python -m robot.libdoc MyLibrary.py MyLibrary.html
/path/to/libdoc_sample/MyLibrary.html

# 中身を確認する
$ open MyLibrary.html 

　
できあがったHTMLはこんな感じです。

Robot Frameworkのライブラリドキュメントでよく見かけるフォーマットです。

　
引き続き、このドキュメントに追加していきます。

ドキュメントのシンタックスを決める

ドキュメントを書く前に、ドキュメントのシンタックスを決めておきます。

ユーザガイドによると、以下のシンタックスが利用できます。
5.1.3 Documentation syntax - Robot Framework User Guide

• Robot Framework documentation syntax
• HTML documentation syntax
• Plain text documentation syntax
• reStructuredText documentation syntax

　
なお、Robot Framework documentation syntax以外にする場合、 ROBOT_LIBRARY_DOC_FORMAT に使用するシンタックスを設定する必要があります。

今回はデフォルトの Robot Framework documentation syntax とします。

Introductionを記述

デフォルトでは

Documentation for test library <ライブラリ名>

となっている部分を記述します。

Pythonのクラスコメントを追加し、ドキュメントを生成します。

class MyLibrary:
    """マイライブラリ"""
    def hello_world(self, name='foo'):
        logger.console(f'hello, world {name} !')

　
生成されたものを見ると、Introductionが差し替わっていました。

キーワードのドキュメントを追加

ソースコード中のメソッドにコメントを追加します。

class MyLibrary:
    """マイライブラリ"""

    def hello_world(self, name='foo'):
        """ハローワールドを出力します"""
        logger.console(f'hello, world {name} !')

　
生成されたものを見ると、キーワードのドキュメントが追加されていました。

Library scopeの変更

Library scopeの設定を変更することで、自動的に変更されます。

class MyLibrary:
    """マイライブラリ"""

    # Library scopeの設定を変更
    ROBOT_LIBRARY_SCOPE = 'TEST SUITE'

　
生成されたものです。

BoldやItalicでの文字装飾

コメント中に

• Bold: *<文字列>*
• Italic: _<文字列>_

と書くことで修飾できます。

• 5.1.3 Documentation syntax - Robot Framework User Guide
• 6.4.3 Inline styles - Robot Framework User Guide

class MyLibrary:
    """マイライブラリ

    *太字です*
    _イタリックです_
    普通です
    """
#...

　
生成されたものです。

　
なお、複数行の太字はうまくいきませんでした。

リスト表示

Markdownと同じように、 ハイフン - を先頭に付けることでリスト表示されます。

なお、リストのネストはなさそうです。

class MyLibrary:
    """マイライブラリ

    *太字です*
    _イタリックです_
    普通です

    - リスト1
    - リスト2
    """

　
生成されたものです。

URLのリンク

URLのリンクは以下の2種類となります。

• https://google.co.jp のようなURLを書く
• [https:/google.co.jp|Googleへ] のような記法にする

　
両者の違いを実際に見てみます。

class MyLibrary:
    """マイライブラリ

    *太字です*
    _イタリックです_
    普通です

    - リスト1
    - リスト2

    Googleへ https://google.co.jp
    こちらも [https://google.co.jp|Googleへ]
    """

　
生成されたものです。

キーワードへの内部リンク

バックスラッシュ (`) を使うことで、キーワードへのリンクとなります。

class MyLibrary:
    """マイライブラリ

    *太字です*
    _イタリックです_
    普通です

    - リスト1
    - リスト2

    Googleへ https://google.co.jp
    こちらも [https://google.co.jp|Googleへ]
    
    `Hello World` へ
    """

　
生成されたものです。

Introductionの Hello World をクリックすると、Keywordsの Hello World へとジャンプします。

クリックすると、このように青字でKeywordsがハイライトされます。

インラインコードスタイル

Markdownだとシングルバッククォート(`) で書きますが、Robot Frameworkではダブルバッククォート(``)で書きます。

class MyLibrary:
    """マイライブラリ

    *太字です*
    _イタリックです_
    普通です

    - リスト1
    - リスト2

    Googleへ https://google.co.jp
    こちらも [https://google.co.jp|Googleへ]

    `Hello World` へ

    ``インラインコードスタイル``

　
生成されたものです。

セクションへの自動リンク

セクション

• Introduction
• Importing
• Shortcuts
• Keywords

については、各単語をシングルバッククォートで囲むことで、自動的に内部リンクが作成されます。

class MyLibrary:
    """マイライブラリ

    セクションへのリンク

    - `introduction`
    - `importing`
    - `shortcuts`
    - `keywords`

　
生成されたものです。

カスタムセクションの作成とカスタムセクションへの内部リンク

カスタムセクションは、 = <セクション名> = で作成できます。

また、シングルバッククォートでセクション名を囲むことで、カスタムセクションへの内部リンクが作成されます。

class MyLibrary:
    """マイライブラリ

    = カスタムセクション =

    ここがカスタムセクション

    = 次のセクション =

    `カスタムセクション` へのリンク

　
生成されたものです。

表

表は以下で生成できます。

• | で区切ると、1列追加
  • | と項目の間には半角スペース が必要
• 列のタイトルは、 = で囲む
• 空白セルは、| の間に半角スペースを入れる (| |)

class MyLibrary:
    """マイライブラリ

    | =タイトル= | =もう一つタイトル= |
    | 1行1列目 | 1行2列目 |
    | | 1列目が空白 |
    | 2列目が空白 | |

　
生成されたものです。

キーワードの引数表示について

Pythonの引数には

• 引数なし
• デフォルト値なしの引数
• デフォルト値ありの引数
• *args
• **kwargs

があるため、それぞれを表示してみます。

class MyLibrary:
#...
    def no_args(self):
        pass
    
    def multi_args(self, one, two='2', *args, **kwargs):
        pass

　
生成されたものです。

　
ざっと書きましたが、これで公式ドキュメントにあるようなライブラリのドキュメントが作れそうです。

ソースコード

GitHubに上げました。libdoc_sample ディレクリの中が今回のものです。
thinkAmi-sandbox/RobotFramework-sample: Robot Framewrok samples