ITの隊長のブログ

ITの隊長のブログです。Pythonを使って仕事しています。最近は機械学習をさわりはじめたお(^ω^ = ^ω^)

Pythonでドキュメント作成

スポンサードリンク

概要

モジュール開発終わったら、ドキュメント作成ですが、面倒なので、生成する方向でやりました。

モジュールのdocstring

GoogleスタイルのPython Docstringsの例 — Sphinx 1.5.6 ドキュメント

Googleが好みだったのでこれでコメントを書いた

わかりやすいREADME

参考

わかりやすいREADME.mdを書く | SOTA

Sphinx

qiita.com

こっちがわかりやすかった。

reStructuredText

reStructuredText入門 — Sphinx 1.5.6 ドキュメント

4. Sphinxでの文章の書き方(reStructuredText) — study sphinx 1 documentation

リファレンスページが最強

themeの変更

build inで用意されているのがいくつか存在する.

HTMLテーマのサポート — Sphinx 1.5.6 ドキュメント

sphinxのハマり

build inされたテーマに変更できない

stackoverflow.com

デフォのテーマで必要な何かをコメントアウトすればよいとのこと.

(ERROR/3) Unknown directive type "seqdiag".

sphinxcontrib-seqdiag — blockdiag 1.0 documentation

入っていないディレクティブは使わないか、使いたきゃinstall

autodocってどうなんじゃろ?

# If extensi

ons (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

この辺のコメントを外す。

class, packagesを図にする

qiita.com

DBスキーマをrstへ変換する

mysqlpostgresqlも対応しているので良い

tk0miya.hatenablog.com