チームメイトのためにdocstringを書こう！ pyconjp2019
10 likes10,890 views
The document discusses various styles and methods for writing docstrings in Python, including reStructuredText, NumPy style, and Google style. It covers the incorporation of type hints in function definitions and usage of tools like Sphinx for generating documentation. Additionally, it highlights the installation of dependencies and necessary configurations for creating structured documentation using automated processes.
チームメイトのためにdocstringを書こう！ pyconjp2019
- 2. docstring • Python 2 def f(arg1): """ """ pass
- 3. • @cocodrips • → →MLOps • : PyDataTokyo 3
- 4. 1. docstring 2. docstring 3. docstring . DocString
- 5. docstring • Python 5 def f(arg1): """ """ pass
- 6. docstring 6 >>> help(f) Help on function f: f(arg1) • docstring help
- 7. docstring • Jupyter Notebook ? help 7
- 8. Docstring • • • type IDE (IDE ) • 8
- 9. 9
- 10. docstring
- 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 • def func(arg1, arg2): “”” ””"
- 13. 13 • TypeHint def func(arg1: int, arg2: str) -> bool: """ :param arg1: arg1 :param arg2: arg2 :return: """
- 14. 14 • module(.py ) docstring - """ """ • Class docstring class Hello: """ """
- 15. docstring 3 • ReStructuredText • NumPy Style • Google Style 15
- 16. ReStructuredText(reST) 16 def func(arg1, arg2): """ :param arg1: 1 :type arg1: 1 :param arg2: 2 :type arg2: 2 :return: :rtype: """
- 17. X def func(arg1: , arg2: ): -> """ :param arg1: 1 :param arg2: 2 :return: """ ReStructuredText - TypeHints
- 18. NumPy style 17 def func(arg1, arg2): """ Parameters ---------- arg1 : 1 1 arg2 : 2 2 Returns ------- """ • •
- 19. NumPy style - TypeHints X def func(arg1: , arg2: ) -> : """ Parameters ---------- arg1 : 1 arg2 : 2 Returns ------- """
- 20. Google Style 18 def func(arg1, arg2): """ Args: arg1 ( 1 ): 1 arg2 ( 2 ): 2 Returns: : """
- 21. 19 • ReStructuredText • • NumPy Style • • Google Style •
- 22. 20 • ReStructuredText • • NumPy Style • • Google Style • TypeHints
- 23. 21 • ReStructuredText • • NumPy Style • • Google Style • TypeHints
- 24. 22 def func(arg1: , arg2: ): -> """ :param arg1: 1 :param arg2: 2 :return: """ ReStructuredText - TypeHints
- 25. PyCharm: 23
- 27. docstring
- 29. ^ω^ 27
- 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. $ pip install Sphinx sphinx-autodoc-typehints # 依存ライブラリのインストール $ python setup.py install X sphinx-apidoc import
- 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. 30 $ cd doc $ make html $ open _build/html/index.html
- 34. !31
- 36. 33
- 37. 34
- 38. : DocString
- 39. DocString • => TypeHints + reST • CI branch GitHub Pages • docstring PR ↑↑↑↑↑↑ ↑↑↑↑↑↑ 36
- 40. DocString • => TypeHints + reST • CI branch GitHub Pages • docstring PR ↑↑↑↑↑↑ ↑↑↑↑↑↑ 37
- 41. doc-cov Pull request 38 # CI内で以下を実行 $ doccov <package> -fmc --output csv > doccov.csv $ doccov-report doccov.csv
- 42. Pull Request / Issue 39 $ pip install doc-cov