CODEWITHSUNDEEP
haskelldocumentation
Jason Hu
Jason Hu

Reputation: 6333

generate documentation with relative paths

I am trying to setup cabal config such that it can generate documentation in a form that I can browse it locally or remotely. So one of the requirement is to generate a correct form of html, i.e. a relative path.

I've searched around but it seems there are too many combinations of options so I think it's better to ask over here and see if anybody knows.

my current config:

documentation: True

other options are irrelevant. and compiler generate links similar to this one:

file:///home/hu/.cabal/share/doc/x86_64-linux-ghc-7.10.3/lens-4.14/html/Control-Lens.html

this makes me only able to read the doc locally. so I would expect in html, it contains the link as:

lens-4.14/html/Control-Lens.html

such that in a remote browser, i can see the link as:

http://linux/ghc-doc/lens-4.14/html/Control-Lens.html

hope that makes sense.

anyone knows what options i need to set to enable this?

Upvotes: 2

Views: 114

Answers (3)

Jason Hu
Jason Hu

Reputation: 6333

I can't really find a solution so i ended up writing my own cgi script that will help me do the transformation. here is the gist:

https://gist.github.com/HuStmpHrrr/b7de3c49f77a925dc6cf85da16a1d231

where pipeline is the one that will correct the hyperlinks. since it's a quick and dirty scripting, it will be appreciated if one can point out what i can improve from this.

also we will need to setup the http server(in my case, it's apache2):

  1. enable cgi

    LoadModule cgi_module /usr/lib/apache2/modules/mod_cgi.so

  2. config your apache to run cgi:

     ScriptAlias /cgis/ $somepath/cgis/
 <Directory "$somepath/cgis">
     AllowOverride None
     Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
     Require all granted
 </Directory>

  3. and place the cgi file over there. it should be able to do the trick.

Upvotes: 0

d8d0d65b3f7cf42
d8d0d65b3f7cf42

Reputation: 2653

Perhaps you want this: http://documentup.com/feuerbach/standalone-haddock

Quote: It generates documentation ... with proper links:

  • links to identifiers inside this package set are relative
  • links to identifiers from external packages lead to hackage

Upvotes: 0

ErikR
ErikR

Reputation: 52039

One option is to use stack -- it creates HTML docs with relative links like you want.

For each package, just run:

stack build --haddock <package-name>

or

stack --resolver ... build --haddock <package-name>

to use a specific resolver. Then look in $HOME/.stack/snapshots/<arch>/<resolver>/<ghc-version>/doc/

Note - <package-name> is just the package name - not including the version.

The caveat is that stack won't rebuild packages - maybe there's a flag for that - but you can always expunge your snapshots directory before starting.

Upvotes: 1

Related Questions