docstringのテンプレートを出力してくれるautoDocstringのVS Code拡張が素敵だった - Qiita
Pythonの関数（メソッド）の内容に合わせてdocstringのテンプレートを生成してくれるautoDocstringというVS Codeの拡張機能をお仕事とプライベートで使っていたら結構気に入ったのでその紹介です。 autoDocstringでできること Pythonの関数やメソッドの引数名や型アノテーションなどに応じたdocstringのテンプレートをVS Code上で生成してくれます。 ※JSDoc的なもの含め、他の言語だと割とその辺をしっかり生成してくれる一方でPythonだと（出力されるdocstringのスタイルがずれていたりなど）個人的にしっくりくるものが無く、今まではスニペット的にクリップボードへ定型文登録などして過ごしていました。 PEP257やGoogleスタイル、NumPyスタイルなどメジャー所のdocstringのスタイルはサポートされています。 ※そもそもdoc
忙しい研究者のためのテストコードとドキュメントの書き方 - Qiita
はじめに 「研究用のプログラムにもテストコードやドキュメント書いたほうがいいよね。」 「分かっちゃいるけど、そんな面倒なことやってられないよ。」 という研究者あるあるを解決すべく、僕が普段実践している開発スタイルを紹介します。 この開発スタイルのすごいところは： テストやドキュメントを一切書かない場合と比べて 追加の工数がほぼゼロ。 普通にコーディングしているだけで、いつのまにかテストコードとドキュメントまでできあがっている。 実装、コメント、テスト、ドキュメントが自然に同期するので、保守しやすい。 Pythonを例に紹介しますが、コメント内にテストを書けるツールと、コメントからドキュメントを生成できるツールをもつ言語ならばどれにでも応用できるはずです。 この開発スタイルに至った背景 ソフトウェア開発において、テストコードやドキュメントを整備することでプログラムの品質が向上することは広く知
Style guide — numpydoc v1.8.0rc0.dev0 Manual
Style guide# This document describes the syntax and best practices for docstrings used with the numpydoc extension for Sphinx. Note For an accompanying example, see example.py. Some features described in this document require a recent version of numpydoc. For example, the Yields section was added in numpydoc 0.6. Overview# We mostly follow the standard Python style conventions as described here: S
sphinx.ext.napoleon – NumPy および Google スタイルの docstring をドキュメントに取り込む — Sphinx 1.5.6 ドキュメント
Napoleon - Marching toward legible docstrings¶ 以下のようなdocstringを書こうとしてみたことはあるでしょうか。 :param path: The path of the file to wrap :type path: str :param field_storage: The :class:`FileStorage` instance to wrap :type field_storage: FileStorage :param temporary: Whether or not to delete the file when the File instance is destructed :type temporary: bool :returns: A buffered writable file descriptor :rtyp
[Python]可読性を上げるための、docstringの書き方を学ぶ（NumPyスタイル） - Qiita
日々Pythonの色々な記事がアップされているものの、あまりdocstringに触れている日本語の記事が少ないな・・ということで書きました。 そもそもdocstringって？ Pythonの関数だったりクラスだったりに記述するコメントです。 JSDocだったりのPython版です。 書き方は、最初結構他の言語と違うな・・という印象を受けました。 docstring書くと何が嬉しいの？ 後で見直したときに、すぐ内容が把握できるよ Guido の重要な洞察のひとつに、コードは書くよりも読まれることの方が多い、というものがあります。 はじめに — pep8-ja 1.0 ドキュメント 最初は少し時間がかかっても、書いておくと後でコードを読み直した時の負担が減ります。 関数などを扱う際に、内容を見たりできるよ jupyter などであれば、nbextentionsでhinterlandを有効化する
![[Python]可読性を上げるための、docstringの書き方を学ぶ（NumPyスタイル） - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/dfaa047843f04e332970c0a74f1e00605d8ee219/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-412672c5f0600ab9a64263b751f1bc81.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk3MiZoPTM3OCZ0eHQ9JTVCUHl0aG9uJTVEJUU1JThGJUFGJUU4JUFBJUFEJUU2JTgwJUE3JUUzJTgyJTkyJUU0JUI4JThBJUUzJTgxJTkyJUUzJTgyJThCJUUzJTgxJTlGJUUzJTgyJTgxJUUzJTgxJUFFJUUzJTgwJTgxZG9jc3RyaW5nJUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JUUzJTgyJTkyJUU1JUFEJUE2JUUzJTgxJUI2JUVGJUJDJTg4TnVtUHklRTMlODIlQjklRTMlODIlQkYlRTMlODIlQTQlRTMlODMlQUIlRUYlQkMlODkmdHh0LWFsaWduPWxlZnQlMkN0b3AmdHh0LWNvbG9yPSUyMzIxMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT01NiZzPThhMGJmMmI1MzM2NDVlNDBlM2UyZGZjNDg1NGJmNTlj%26mark-x%3D142%26mark-y%3D57%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZoPTc2Jnc9NzcwJnR4dD0lNDBzaW1vbnJpdGNoaWUmdHh0LWNvbG9yPSUyMzIxMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT0zNiZ0eHQtYWxpZ249bGVmdCUyQ3RvcCZzPTAzNTFhOWFiMzVlNjQwNDIxNzY0MDEzZTMzZTZhNmZk%26blend-x%3D142%26blend-y%3D486%26blend-mode%3Dnormal%26s%3D2c9035999f00da0029accbe8604c4563)
ひょっとして docstring と doctest、あまり浸透してない? | site-hhs
Python 使いにとっては空気のようなもの、と思い込んでたし、ワタシが同僚に Python を伝えるなら、かなり真っ先に教えるものなので、ちょっとわかってないのかしら、という記事を見つけてしまってヘコむ。 Sphinxは、Doxygenや javadoc、perldoc などの「コメントからドキュメントを自動生成するツール」ではない。本来。あくまでも「ドキュメントを作るツール」ね。まずは。そして、Doxygenのように使うことも出来る。これが sphinx-apidoc ね。けどこれはあくまでもオカズ。主食じゃないです。 名言されてはいないけれど、ワタシはSphinxが目指すことには一つには「Doxygen的自動生成ドキュメントへの反旗」があるんじゃないかと思っている。確かに「コードからドキュメント自動生成」は、開発者の手間だけは減らせるけれど、わたしがみるに、9割の「Doxygen的ド
Python: docstring を書いてみよう - CUBE SUGAR CONTAINER
Python の docstring というのは、モジュールやクラス、関数などにつける説明文のこと。 単純なコメントとの違いは、より仕様に近い内容を記述しておくことで API のドキュメントとして利用できる他、別のドキュメントから内容を読み込んで使ったりすることができる。 今回は docstring の書かれたサンプルコードを元に、REPL からその内容を参照したり、ドキュメンテーションツール Sphinx でその内容を読み込むというのを試してみる。 docstring の書かれたソースコードを用意する 以下が docstring の書かれた Python のソースコード。 内容については FizzBuzz 問題を題材にしている。 モジュールや関数の先頭で “”“ や ‘’‘ を使ってコメントを書いておくと、それが自動的に docstring として扱われることになる。 #!/usr/bi
Python pydocの使い方、書き方とhtml出力の方法 - Symfoware
標準ライブラリのdocstring Pythonの標準ライブラリではdocstringが書いてありますが、ライブラリによって引数の書き方が異なっています。 たとえば os.py では def makedirs(name, mode=0777): """makedirs(path [, mode=0777]) Super-mkdir; create a leaf directory and all intermediate ones. Works like mkdir, except that any intermediate path segment (not just the rightmost) will be created if it does not exist. This is recursive. """ このようにdocstringの一行目に引数を記載していますが、 cod
Sphinxドメイン — Sphinx 1.5.6 ドキュメント
ドメインとは何か？¶ 当初、Sphinxは一つのプロジェクトと、Pythonの言語のドキュメントのために作られました。その後少し経って、汎用的なドキュメントツールとして作り直されましたが、Pythonモジュールのドキュメントのため、という部分はツールの奥深くまで根を伸ばしたままでした。 function などのもっとも基本的なディレクティブは、Pythonのオブジェクトのために設計されました。しばらくたって、Sphinxはいくらか人気が出てきて、C/C++のプロジェクト、JavaScript, reStructuredText(このドキュメントのように)など、さまざまな異なる目的で使用したい、という要求が出てきました。 今までも書けないことはありませんでしたが、1.0からは、もっと簡単に、Sphinxでサポートしていない異なるプログラミング言語を使用したプロジェクトのドキュメントでも使える
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
02-505_チームメイトのためにdocstringを書こう(ku-mu)