Downloaded 20 times
Uploaded bycocodrips
チームメイトのためにdocstringを書こう！ pyconjp2019
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.
More Related Content
チームメイトのためにdocstringを書こう！ pyconjp2019
- 1.
- 2.
- 3. • @cocodrips • → →MLOps • : PyDataTokyo 3
- 4. 1. docstring 2. docstring 3.docstring . DocString
- 5.
- 6. docstring 6 >>> help(f) Help onfunction f: f(arg1) • docstring help
- 7. docstring • Jupyter Notebook? help 7
- 8. Docstring • • • type IDE (IDE ) • 8
- 9.
- 10.
- 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.
- 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 • NumPyStyle • Google Style 15
- 16. ReStructuredText(reST) 16 def func(arg1, arg2): """ :paramarg1: 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 • • NumPyStyle • • Google Style •
- 22. 20 • ReStructuredText • • NumPyStyle • • Google Style • TypeHints
- 23. 21 • ReStructuredText • • NumPyStyle • • Google Style • TypeHints
- 24. 22 def func(arg1: ,arg2: ): -> """ :param arg1: 1 :param arg2: 2 :return: """ ReStructuredText - TypeHints
- 25.
- 26.
- 27.
- 28.
- 29.
- 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 installSphinx 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.
- 35.
- 36.
- 37.
- 38.
- 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