[feat] Doctest Japanese transcript

source/pyconapac/doctest.rst.txt

@@ -6,6 +6,10 @@ doctest
 
     対話的な実行例をテストする
 
+.. doctestは標準ライブラリにあります。
+    私は好きなライブラリです。
+    どんなライブラリかというと「Test interactive Python examples」
+
 関数のdocstring
 ============================================================
 
@@ -15,17 +19,38 @@ doctest
 
 https://docs.python.org/ja/3/glossary.html#term-docstring
 
+.. 関数にはdocstringというものがありますよね。
+    用語集を引くと、
+    A string literal which appears as the first expression in a function.
+    it(docstring) is the canonical place for documentation of the object.
+
 ドキュメンテーション文字列 とも
 --------------------------------------------------
 
 * https://docs.python.org/ja/3/tutorial/controlflow.html#tut-docstrings
 * **三連引用符** を用い、複数行にまたがった文字列リテラルとすることがほとんど
 
+.. docstringはドキュメンテーション文字列(Documentation Strings)とも呼ばれます。
+    クォートを3つ連続させた文字列にします。
+    改行を含められるので、複数行にまたがった文字列がほとんどです（TODO スライド組み換え？）
+    百聞は一見にしかずです。
+
 .. https://docs.python.org/ja/3/tutorial/introduction.html#text
 
 docstringの例
 --------------------------------------------------
 
+.. code-block:: python
+
+    def fizzbuzz(number: int) -> str:
+        """FizzBuzzゲームを解く関数（：1行要約）
+
+        ...（後述）...
+        """
+
+.. fizzbuzz関数にdocstringを書きました。
+    関数定義（def）の直後に三連引用符を使った文字列を書いています
+
 .. テストを通すための定義
     >>> def fizzbuzz(number: int) -> str:
     ...     if number % 3 == 0 and number % 5 == 0:
@@ -37,21 +62,16 @@ docstringの例
     ...     else:
     ...         return str(number)
 
-.. code-block:: python
-
-    def fizzbuzz(number: int) -> str:
-        """FizzBuzzゲームを解く関数（：1行要約）
-
-        ...（後述）...
-        """
-
 Python対話モードの **実行例をdocstringに書く**
 --------------------------------------------------
 
 .. literalinclude:: ../../samplecode/python-testing/doctest-example/fizzbuzz.py
     :language: python
     :lines: 1-3,6-9,14
 
+.. docstringの続きには、Pythonの対話モードでfizzbuzz関数を実行したときの実行例を書きます。
+    1のときは文字列1、3のときはFizz
+
 対話モードの実行例を **テストとして実行**
 ============================================================
 
@@ -62,6 +82,9 @@ Python対話モードの **実行例をdocstringに書く**
 
 * :command:`python -m doctest fizzbuzz.py`
 
+.. docstringに実行例を書いたファイルだけを作り、python -m doctestに相対パスを渡してテストを実行します。
+    passするときは何もいいません
+
 実行結果の確認（:command:`-v` オプション）
 --------------------------------------------------
 
@@ -77,6 +100,9 @@ Python対話モードの **実行例をdocstringに書く**
     4 passed and 0 failed.
     Test passed.
 
+.. -vオプションを付けてdoctestを実行すると、実行結果が詳細に出力されます。
+    テスト4つが通り、失敗はなし。テスト全体はpassしました
+
 関数のdocstringに限らず使えます
 --------------------------------------------------
 
@@ -85,6 +111,9 @@ nikkieはテキストファイル（特にreStructuredText）で頻繁に使用
 * 書籍執筆
 * **発表資料** 作成（本資料含む）
 
+.. 私はPythonファイルに限らずdoctestを使います。
+    このスライドのPythonの対話例はdoctestが通っているので、不安を感じずに登壇できています
+
 利用シーン：ライブラリのドキュメントにも
 --------------------------------------------------
 
@@ -98,9 +127,16 @@ nikkieはテキストファイル（特にreStructuredText）で頻繁に使用
 
 https://scikit-learn.org/stable/modules/generated/sklearn.metrics.f1_score.html
 
+.. doctestは有名なライブラリのドキュメントでも使われています。
+    これはscikit-learnの例です（TODO ソースコード？）
+    ？PyTorch
+
 doctestの注意点
 ============================================================
 
+.. doctestには気をつけなければならない点があります。
+    先ほどのコードとの違いは文字列がダブルクォートという点だけです
+
 .. 以下のコードのdoctestを通すだけのコード（doctest: +SKIPがtrimされないため）
     >>> def fizzbuzz(number):
     ...     print('"Fizz"')
@@ -141,6 +177,10 @@ doctestの注意点
     
     ***Test Failed*** 1 failures.
 
+.. このテストは落ちてしまいます。
+    期待値はダブルクォートで囲まれたFizz、実際の値はシングルクォートで囲まれたFizz。
+    doctestはこの2つを別物として扱うので、テストが落ちます
+
 焦点：対話モードの出力結果として一致するか
 --------------------------------------------------
 
@@ -153,13 +193,22 @@ doctestの注意点
 
 * doctestでも文字列はシングルクォートにする必要がある
 
+.. ポイントとしては、doctestは対話モードの出力結果として一致するかを見ているので、それを念頭に考えるということです。
+    対話モードでダブルクォートで囲んだ文字列を入力しても、出力はシングルクォート囲みですね。
+    doctestでは文字列はシングルクォートにする必要がある
+
 対話モードは ``repr`` 関数の返り値
 --------------------------------------------------
 
     repr() 関数はインタープリタに読める（略）表現を返すためのもの
 
 https://docs.python.org/ja/3/tutorial/inputoutput.html#fancier-output-formatting
 
+.. reprという組み込み関数があります。
+    対話例の出力は、reprの返り値と思っていただければと思います
+
+.. TODO? __repr__
+
 doctestから見るテストコードの書き方
 ============================================================
 
@@ -170,6 +219,10 @@ doctestから見るテストコードの書き方
 * 実行例を書くだけで、関数に **ある値を入力したときの出力** を検証できた
 * *3A* という見方を導入
 
+.. 別の話題、doctestから見るテストコードの書き方
+    実行例を書くだけで、関数にある値を入力したときの出力を検証できましたが、
+    ここで3A(three A)という見方を導入します
+
 3A
 --------------------------------------------------
 
@@ -179,17 +232,21 @@ doctestから見るテストコードの書き方
 
 https://xp123.com/articles/3a-arrange-act-assert/
 
+.. 3つのAでして、Arrange・Act・Assertです。
+
 3Aで見るdoctest
 --------------------------------------------------
 
-コメントを使った説明のため、対話モードで示します
+※コメントを使って説明するため、対話モードで示します
 
 .. code-block:: pycon
 
     >>> number = 3
     >>> fizzbuzz(number)
     'Fizz'
 
+.. docstringではなく対話モードを使って、3Aとは何かを示していきます
+
 Arrange
 --------------------------------------------------
 
@@ -202,6 +259,8 @@ Arrange
     >>> fizzbuzz(number)
     'Fizz'
 
+.. Arrangeはテストの準備です。ここでは簡単ですが、number変数に3を代入しました
+
 Act
 --------------------------------------------------
 
@@ -214,6 +273,9 @@ Act
     >>> fizzbuzz(number)
     'Fizz'
 
+.. テスト対象の関数の実行がAct
+    numberをfizzbuzz関数に渡す
+
 Assert
 --------------------------------------------------
 
@@ -226,9 +288,17 @@ Assert
     >>> fizzbuzz(number)
     'Fizz'
 
+.. 返り値が期待値と一致するかを検証するのがAssert
+    この3Aをテストを書くときに意識しています。
+
 🥟doctest まとめ
 ============================================================
 
 * 対話モードの **実行例を、docstringに書くだけ**！
 * :command:`python -m doctest` にPythonファイルを渡してテスト実行
 * テストコードの一歩目として非常にオススメです
+
+.. doctestをまとめますと
+    対話モードの実行例を、docstringに書くだけで、テストできちゃう！
+    コマンドはpython -m doctestです。
+    テストコードを書いてみようと思ったらdoctestが一番書きやすいと思います