AKAGI Rails

鉄道模型シミュレーターで遊んでいたはずが、気づいたらPythonなども。

Pydoc-Markdown をお試し

Pythonのdocstringを自動でドキュメント化するときはSphinxが定番ですが,それに代わるPydoc-Markdownというのを見つけたので,備忘録がてら紹介します。

pypi.org

インストール

pipからインストールできます。pipxでのインストールが推奨されています。私は無視して普通にpipでインストールしましたが,言われたとおりにするとしたら

pip install pipx
pipx install pydoc-markdown

どうせ必要になるので,MkDocsも入れておきます。MkDocs-Materialも。

お試し

Pydoc-MarkdownのGithubからまるごとダウンロードしてきて,Pydoc-MarkdownでPydoc-Markdownのドキュメントを作ってみます。

pydoc-markdown-develop (pydoc-markdown.yamlとかreadme.mdがあるディレクトリ) でターミナルを開き,次のコマンドを実行すると,ブラウザが立ち上がりlocalhostでドキュメントが読めます。

pydoc-markdown  --watch-and-serve -o

もう少し詳しく

pydoc-markdown.yaml の中身を見てみると,ここでドキュメントの構造をはじめいろいろなオプションを設定していることが分かります。

pydoc-markdown.yamlのひな型は

pydoc-markdown --bootstrap-mkdocs

で生成できます。

ただしコイツの書き方の詳しいところが私もよく分かっていません。pydoc-markdown-develop/pydoc-markdown.yamlを雰囲気でマネするのがいいかも。

HTML化

./docs/build をさらにMkDocsでビルドすると,HTMLドキュメントにできます。手順はCaldia氏のMkDocsマニュアルが参考になりますのでご参照ください。

蛇足

VRMNXpy用の拡張パッケージを作れないかと思っていろいろ試していますが,マニュアル作りのことも考えておかないといけません。 しかしSphinxではコードを一通り実行してdocstringを整形するので,実行中にvrmapiのImportErrorが出ると止まってしまい,うまくいきません。

その点Pydoc-Markdownは,コードを実行せずにdocstringをパースして整形してくれるので,この問題を回避できる…と思われたのですが,謎のエラーに遭遇しておりこちらもうまくいっていません。