Generazione di documentazione per il mio codice con Haddock e stack

Question

Ho annotato il mio codice in stile Haddock e desidero generare documentazione in grado di navigare. Poiché sto anche usando lo stack, voglio integrare la generazione della documentazione nel flusso di lavoro. Tuttavia, non sono ancora stato in grado di generare nulla di utile.

posso correre

stack haddock 

e sarà generare la documentazione nello stile che voglio (si trovano in profondità all'interno ~/.stack/), ma sembra solo per generare la documentazione per i pacchetti che dipendono da, piuttosto che per la il mio codice personale

Quando eseguo

stack haddock --help 

ho l'impressione che posso usare l'argomento aggiuntivo --haddock per generare la documentazione per il mio progetto e --no-haddock-deps di lasciare fuori la documentazione per le mie dipendenze. Tuttavia, quando corro

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

niente sembra accadere. Se I stack clean per prima cosa ricompilerà tutto il mio codice ma non viene generato alcun output che sembra riguardare in alcun modo la documentazione.

Come soluzione intermedia Inoltre ho provato a fare funzionare Haddock di per sé, vale a dire

haddock my-source.hs 

ma poi ho un errore che non riesce a trovare un modulo il file dipende da (che viene installato localmente da stack). Questo mi dà l'impressione che la generazione della documentazione dovrà passare attraverso lo stack in qualche modo. Ho cercato, ma non ho trovato alcuna spiegazione relativa alla configurazione dei miei file .cabal e stack.yaml per la documentazione.

TL; DR

Come posso usare stack e Haddock per generare la documentazione per il codice nel mio pacchetto?

Answer 1

In base allo this ticket sul tracker degli errori dello stack, Stack può attualmente solo creare documentazione per le librerie, ma non per gli eseguibili.

Cabal può essere configurato per lavorare con i database dello stack con questo comando:

cabal configure --package-db=clear --package-db=global --package-db=$(stack path --snapshot-pkg-db) --package-db=$(stack path --local-pkg-db) 

dopo il quale è possibile eseguire cabal haddock --executables per generare la documentazione.

A proposito, stack haddock è solo una scorciatoia per stack build --haddock, quindi non è necessario scrivere stack haddock --haddock.

Answer 2

https://www.reddit.com/r/haskell/comments/5ugm9s/how_to_generate_haddock_docs_for_nonlibrary_code/ddtwqzc/

La seguente soluzione funziona solo quando vengono specificati i singoli file:

stack exec -- haddock --html src/Example.hs src/Main.hs --hyperlinked-source --odir=dist/docs