コードにHaddockスタイルで注釈を付けたので、参照可能なドキュメントを生成したいと思います。スタックも使用しているので、ドキュメントの生成をワークフローに統合したいと思います。しかし、私はまだ有用なものを生成することができていません。
走れる
stack haddock
そしてそれは私が望むスタイルでドキュメントを生成します(~/.stack/
の奥深くにあります)が、私自身のコードではなく、私が依存しているパッケージのドキュメントを生成するようです。
走ると
stack haddock --help
追加の引数--haddock
を使用して自分のプロジェクトのドキュメントを生成し、--no-haddock-deps
を使用して依存関係のドキュメントを省略できるという印象を受けます。しかし、私が走ると
stack haddock --haddock --no-haddock-deps
何も起こらないようです。最初にstack clean
すると、すべてのコードが再コンパイルされますが、ドキュメントに関連しているように見える出力は生成されません。
中間的な解決策として、Haddockを単独で実行してみました。
haddock my-source.hs
しかし、ファイルが依存しているモジュール(スタックによってローカルにインストールされている)が見つからないというエラーが表示されます。これは、ドキュメントの生成が何らかの形でスタックを通過する必要があるという印象を私に与えます。ドキュメント用に.cabal
ファイルとstack.yaml
ファイルを構成することに関連する説明を探しましたが、実際には見つかりませんでした。
TL; DR
スタックとHaddockを使用して、自分のパッケージ内のコードのドキュメントを生成するにはどうすればよいですか?
スタック課題トラッカーの このチケット によると、Stackは現在、ライブラリのドキュメントのみをビルドでき、実行可能ファイルはビルドできません。
Cabalは、次のコマンドでスタックデータベースと連携するように構成できます。
cabal configure --package-db=clear --package-db=global --package-db=$(stack path --snapshot-pkg-db) --package-db=$(stack path --local-pkg-db)
その後、cabal haddock --executables
を実行してドキュメントを生成できます。
ちなみに、stack haddock
はstack build --haddock
のショートカットにすぎないので、stack haddock --haddock
を書く必要はありません。
次の解決策は、個々のファイルが指定されている場合にのみ機能します。
stack exec -- haddock --html src/Example.hs src/Main.hs --hyperlinked-source --odir=dist/docs