haskell - lista - Generando documentación para mi propio código con Haddock y pila
html orden (2)
He anotado mi código en estilo Haddock y me gustaría generar documentación para navegar. Como también estoy usando la pila, quiero integrar la generación de documentación en el flujo de trabajo. Sin embargo, todavía no he podido generar nada útil.
puedo correr
stack haddock
y generará la documentación en el estilo que deseo (que se encuentra en el fondo ~/.stack/ ), pero parece que solo genera la documentación de los paquetes de los que dependo, en lugar de mi propio código.
Cuando corro
stack haddock --help
Me da la impresión de que puedo usar el argumento adicional --haddock para generar documentación para mi propio proyecto, y --no-haddock-deps para dejar de lado la documentación para mis dependencias. Sin embargo, cuando corro
stack haddock --haddock --no-haddock-deps
nada parece suceder Si stack clean primero, se volverá a compilar todo mi código pero no se generará ningún resultado que parezca estar relacionado de alguna manera con la documentación.
Como solución intermedia, también he intentado ejecutar Haddock por sí mismo, es decir,
haddock my-source.hs
pero luego recibo un error que indica que no puede encontrar un módulo del que depende el archivo (que se instala localmente por pila). Esto me da la impresión de que la generación de documentación tendrá que pasar por la pila de alguna manera. He buscado, pero en realidad no he encontrado ninguna explicación relacionada con la configuración de mis archivos .cabal y stack.yaml para la documentación.
TL; DR
¿Cómo puedo usar stack y Haddock para generar documentación para el código en mi propio paquete?
De acuerdo con github.com/commercialhaskell/stack/issues/729 en el rastreador de problemas de pila, actualmente, Stack solo puede compilar documentación para bibliotecas, pero no ejecutables.
Cabal puede configurarse para trabajar con las bases de datos de pila con este comando:
cabal configure --package-db=clear --package-db=global --package-db=$(stack path --snapshot-pkg-db) --package-db=$(stack path --local-pkg-db)
después de lo cual puede ejecutar cabal haddock --executables para generar la documentación.
Por cierto, la stack haddock es solo un acceso directo para la stack build --haddock , por lo que no hay necesidad de escribir la stack haddock --haddock .
La siguiente solución solo funciona cuando se especifican archivos individuales:
stack exec -- haddock --html src/Example.hs src/Main.hs --hyperlinked-source --odir=dist/docs