Создание документации для моего собственного кода с помощью Haddock и stack

Я аннотировал свой код в стиле Haddock и хотел бы создать документацию, доступную для просмотра. Поскольку я также использую стек, я хочу интегрировать создание документации в рабочий процесс. Тем не менее, я еще не смог создать ничего полезного.

Я могу запустить

stack haddock

и он будет генерировать документацию в стиле, который я хочу (который можно найти глубоко внутри ~/.stack/), но, по-видимому, он создает документацию для пакетов, на которые я полагаюсь, а не на собственный код.

Когда я запустил

stack haddock --help

У меня создается впечатление, что я могу использовать дополнительный аргумент --haddock для создания документации для моего собственного проекта и --no-haddock-deps, чтобы оставить документацию для моих зависимостей. Однако, когда я запускаю

stack haddock --haddock --no-haddock-deps

ничего не происходит. Если я stack clean сначала, он перекомпилирует весь мой код, но не генерируется вывод, который каким-либо образом связан с документацией.

В качестве промежуточного решения я также попытался запустить "Пикша" сам по себе, т.е.

haddock my-source.hs

но затем я получаю сообщение об ошибке, что он не может найти модуль, от которого зависит файл (который устанавливается локально стеком). Это создает впечатление, что создание документации придется каким-то образом пройти через стек. Я искал, но не нашел никаких объяснений, связанных с настройкой файлов .cabal и stack.yaml для документации.

TL; DR

Как я могу использовать stack и Haddock для создания документации для кода в моем собственном пакете?

Ответы

Ответ 1

В соответствии с этим билетом в трекере проблемы с стеком, 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.