Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

チームメイトのためにdocstringを書こう! pyconjp2019

5,532 views

Published on

docstringとは、コード内に書くドキュメントです。
docstringを書いておくことによってクラスや関数の役割を伝えることができます。

初心者の方や、分析でPythonを使ってる方たちにはあまり馴染みがないかもしれません。

メンテナンスしやすいコードを書くための1つの術として、
今回はdocstringについて

- どんなことを書くべきなのか
- どんな書き方があるのか
- どんな情報を埋め込めるのか

ということをお話したいと思います。

Published in: Engineering
  • Be the first to comment

チームメイトのためにdocstringを書こう! pyconjp2019

  1. 1. docstring !! !1
  2. 2. docstring • Python 2 def f(arg1): """ """ pass
  3. 3. • @cocodrips • 
 → 
 →MLOps • :
 PyDataTokyo 
 3
  4. 4. 1. docstring 2. docstring 3. docstring . DocString
  5. 5. docstring • Python 5 def f(arg1): """ """ pass
  6. 6. docstring 6 >>> help(f) Help on function f: f(arg1) • docstring help 

  7. 7. docstring • Jupyter Notebook ? 
 help 7
  8. 8. Docstring • • 
 • type 
 IDE (IDE ) • 8
  9. 9. 9
  10. 10. docstring
  11. 11. 11 def func(arg1, arg2): “”" 1 0 :param arg1: arg1 :type arg1: int #arg1 :param arg2: arg2 :type arg2: str #arg2 :rtype: bool # :return: """
  12. 12. 12 • def func(arg1, arg2): “”” ””"
  13. 13. 13 • TypeHint def func(arg1: int, arg2: str) -> bool: """ :param arg1: arg1 :param arg2: arg2 :return: """
  14. 14. 14 • module(.py ) docstring - """ """ • Class docstring class Hello: """ """
  15. 15. docstring 3 • ReStructuredText • NumPy Style • Google Style 15
  16. 16. ReStructuredText(reST) 16 def func(arg1, arg2): """ :param arg1: 1 :type arg1: 1 :param arg2: 2 :type arg2: 2 :return: :rtype: """
  17. 17. X def func(arg1: , arg2: ): -> """ :param arg1: 1 :param arg2: 2 :return: """ ReStructuredText - TypeHints
  18. 18. NumPy style 17 def func(arg1, arg2): """ Parameters ---------- arg1 : 1 1 arg2 : 2 2 Returns ------- """ • 
 •
  19. 19. NumPy style - TypeHints X def func(arg1: , arg2: ) -> : """ Parameters ---------- arg1 : 1 arg2 : 2 Returns ------- """
  20. 20. Google Style 18 def func(arg1, arg2): """ Args: arg1 ( 1 ): 1 arg2 ( 2 ): 2 Returns: : """
  21. 21. 19 • ReStructuredText • • NumPy Style • • Google Style •
  22. 22. 20 • ReStructuredText • • NumPy Style • • Google Style • TypeHints
  23. 23. 21 • ReStructuredText • • NumPy Style • • Google Style • TypeHints
  24. 24. 22 def func(arg1: , arg2: ): -> """ :param arg1: 1 :param arg2: 2 :return: """ ReStructuredText - TypeHints
  25. 25. PyCharm: 23
  26. 26. VS Code: autoDocsring 24
  27. 27. docstring
  28. 28. Sphinx 26 •知的で美しいドキュメント 
 ( ) •
  29. 29. ^ω^ 27
  30. 30. class Person: """ """ def __init__(self, age: int, name: str): self.age = age self.name = name def rest_doc_sample(age: int, name: str) -> Person: """Person :param age: :param name: :return: Person """ # ... return Person(age, name) 28 sample_package/simple_rest.py
  31. 31. $ pip install Sphinx sphinx-autodoc-typehints # 依存ライブラリのインストール $ python setup.py install X sphinx-apidoc import 
 

  32. 32. sphinx-apidoc 29 # 設定ファイルを作る & ドキュメントの雛形を生成 $ sphinx-apidoc -F -a -o ./doc ./sample_package doc ├── Makefile ├── _build ├── _static ├── _templates ├── conf.py ├── index.rst 設定ファイル • Extensionsに以下を追加 • sphinx_autodoc_typehints • テーマを変更 • sphinx_rtd_theme • Numpy/Google Styleを
 採用する場合は拡張が必要
  33. 33. 30 $ cd doc $ make html $ open _build/html/index.html
  34. 34. !31
  35. 35. … • Quick Start • •
  36. 36. 33 

  37. 37. 34
  38. 38. : DocString
  39. 39. DocString • 
 => TypeHints + reST • CI branch 
 GitHub Pages • docstring PR 
 ↑↑↑↑↑↑ ↑↑↑↑↑↑ 36
  40. 40. DocString • 
 => TypeHints + reST • CI branch 
 GitHub Pages • docstring PR 
 ↑↑↑↑↑↑ ↑↑↑↑↑↑ 37
  41. 41. doc-cov Pull request 38 # CI内で以下を実行 $ doccov <package> -fmc --output csv > doccov.csv $ doccov-report doccov.csv
  42. 42. Pull Request / Issue
 39 $ pip install doc-cov

×