日々ブログ

日々のくらしの中で思ったこと

【プログラミング】技術ドキュメントを作成するsphinx を使ってみた感想

技術ドキュメントを作成する際に、よく使われているsphinxを使ってみました。
使い方解説!までできればよかったのですが、 なかなかできることが多く、うまいことまとまりませんでした。
今回は、ある程度使ってみた感想を記載したいと思います。

f:id:xinformation:20220220120249p:plain

sphinxとは

技術ドキュメントを作成するのに人気のツールですね。
プログラマが文書を書きたくなるツール」というのがキャッチフレーズですね。
プログラマというのは、「プログラム動いているのに文書なんて必要あるの?時間の無駄では?」と文書を書きたがらない職種なんですが、 そんなプログラマにも使えるような設計を目指しています。
そうした背景からgithubにも連携にも対応していることから、プログラマに人気になったツールです。
pythonスクリプトを使ってhtml文書を作成することができます。
イメージとしては、LaTexpython版でしょうか。

採用例(opencv

OSSのドキュメントなどによく使われています。
ソフトウェアの規模が大きくなると、 ドキュメントが1ページでは収まりきらなくなるので、文書を管理するためのツールが必要になるわけです。
かなり厳密に行うと、設計のドキュメントだけではなく、テスト結果やらソースコードのコメントを文書化して体系化することができます。
たとえば、opencvのドキュメントにも採用されています。
特徴としては、

  1. 目次を自動生成できる
  2. 検索機能
  3. 関数名と使い方を文書化(ソースコードのコメントから作成可能)

f:id:xinformation:20220220112018p:plain

opencv.jp

使ってみた感想

ここからは使ってみた感想です。
正直言うと使いこなすのは結構大変そうです😅。

導入は簡単

導入は非常に簡単です。 pip でsphinxパッケージをインストールします。

pip install sphinx

インストールが完了したら、 下記コマンドを実行すれば文書作成環境を作成できます。

sphinx-quickstart

実行すると下記の質問にyesかnoで答えましょう

  1. ソースと文書の作成結果のファイルを分けるか
  2. プロジェクト名
  3. 作者名
  4. リリース番号
  5. 言語

実行すると、下図のようなフォルダ群が生成されます。

f:id:xinformation:20220220114353p:plain

文書の作成方法

ここまで来れば、文書作成のためにmake.batがあるフォルダで次のコマンドを実行します。

make html

実行すると、 buildフォルダに作成した結果が格納されています。
index.htmlを開くとサンプルページが作成されていて開くと、下のような図です。

無事に文書が作成されていますね。
お疲れさまでした。
f:id:xinformation:20220220114729p:plain

rstファイルに馴染みが無い

作成までは簡単なのですが、それを使って色々凝ったことやりたいことに困ります。
まず、基本的にrstファイルを編集することで文書を編集していくのですが、 作成方法がなかなか難しい。
たとえば、ページを追加して目次を作成したい場合、下図のような記述であれば問題ありません。
f:id:xinformation:20220220115525p:plain

しかし、下図のように改行が足りないとエラーが出てしまいます。
rstファイルの記述法になれていないと、使いこなせなさそうです。

f:id:xinformation:20220220115236p:plain

<上記の場合のエラー:オプションを指定する部分の書き方が間違っているというエラー> f:id:xinformation:20220220115731p:plain

凝ったことをやるための道のりが遠い

ここからは愚痴のような感じになるのですが、 凝ったことをやろうと思うと、ライブラリをインストールして設定ファイルを変更してとやることが多い上に、 できたと思っても、実行エラーに悩まされます。
おそらくsphinxで一番やりたい、ソースコードのヘッダコメントの文書化ですら、 まともにやろうとすると1時間以上はかかります。
加えて、すでに存在している開発プロジェクトにおいて導入しようとするとめちゃくちゃ時間がかかります。
自分の場合は1日かかっても駄目で心がくだけました。
本とか読んで勉強したいと思います。