haddock & web-friendly library links?
My library uses others (including base & wxHaskell), and so references to
types & identifiers from those libraries show up in my Haddock docs. When I
put the docs on the web, the links are bogus. How can I get those links to
be web-accessible versions instead of my local versions?
Similarly, I want to package up my library so that others can build on top
of it and have their published haddock documentation contain web-accessible
pointers to my doc.
Have these issues been thought through? Thanks,
- Conal
---------- Forwarded message ----------
From: Doaitse Swierstra
Conal Elliott wrote:
My library uses others (including base & wxHaskell), and so references to types & identifiers from those libraries show up in my Haddock docs. When I put the docs on the web, the links are bogus. How can I get those links to be web-accessible versions instead of my local versions?
Similarly, I want to package up my library so that others can build on top of it and have their published haddock documentation contain web-accessible pointers to my doc.
Have these issues been thought through? Thanks,
I'm not suggesting that this is a long-term solution, but Haddock does let you link to docs at an arbitrary URL, using the --read-interface flag. This isn't exposed through Cabal, but you can always find out the Haddock command that Cabal is executing and run a modified version by hand. Ultimately I expect as part of the Hackage project we should automatically generate Haddock docs for all the packages and link them together. This needs some thought, perhaps it's something we can talk about at Hac. Another thing we could consider doing is putting a public Haddock URL in the .cabal file, and propagating this into the package configuration. Then when you generate Haddock docs there could be an option to link to either local or external docs for other packages. Cheers, Simon
I like your idea of placing a Haddock package URL in the .cabal file. Given
the creativity of the Haskell community, it'll be important to have a
mechanism for these cross-project links. I hope it gets some attention at
Hac. Cheers, - Conal
On 12/15/06, Simon Marlow
Conal Elliott wrote:
My library uses others (including base & wxHaskell), and so references to types & identifiers from those libraries show up in my Haddock docs. When I put the docs on the web, the links are bogus. How can I get those links to be web-accessible versions instead of my local versions?
Similarly, I want to package up my library so that others can build on top of it and have their published haddock documentation contain web-accessible pointers to my doc.
Have these issues been thought through? Thanks,
I'm not suggesting that this is a long-term solution, but Haddock does let you link to docs at an arbitrary URL, using the --read-interface flag. This isn't exposed through Cabal, but you can always find out the Haddock command that Cabal is executing and run a modified version by hand.
Ultimately I expect as part of the Hackage project we should automatically generate Haddock docs for all the packages and link them together. This needs some thought, perhaps it's something we can talk about at Hac.
Another thing we could consider doing is putting a public Haddock URL in the .cabal file, and propagating this into the package configuration. Then when you generate Haddock docs there could be an option to link to either local or external docs for other packages.
Cheers, Simon
I fiddled with --read-interface to link to other-library docs at URLs. I'm
trying to go through cabal and use --haddock-arg (a flag I recently added)
to get additional flags to haddock. What seems to be happening is that
--use-package wins over --read-interface for the same package, regardless of
the order in which they're listed. The only way I can get the other-library
links to point to web-documentation instead of local versions is to add
--read-interface and *remove* the corresponding --use-package. Is that
behavior what you intend? Given the use-package bias, I can't figure a way
to get my web links via cabal. Using haddock manually would be quite a pain
also, since I'm relying on cabal to preprocess all of my modules with
-D__HADDOCK__ before passing them on to Haddock. The preprocessed versions
come & go invisibly.
Are you aware of the use-package bias? Can you think of a work-around?
- Conal
On 12/15/06, Simon Marlow
Conal Elliott wrote:
My library uses others (including base & wxHaskell), and so references to types & identifiers from those libraries show up in my Haddock docs. When I put the docs on the web, the links are bogus. How can I get those links to be web-accessible versions instead of my local versions?
Similarly, I want to package up my library so that others can build on top of it and have their published haddock documentation contain web-accessible pointers to my doc.
Have these issues been thought through? Thanks,
I'm not suggesting that this is a long-term solution, but Haddock does let you link to docs at an arbitrary URL, using the --read-interface flag. This isn't exposed through Cabal, but you can always find out the Haddock command that Cabal is executing and run a modified version by hand.
Ultimately I expect as part of the Hackage project we should automatically generate Haddock docs for all the packages and link them together. This needs some thought, perhaps it's something we can talk about at Hac.
Another thing we could consider doing is putting a public Haddock URL in the .cabal file, and propagating this into the package configuration. Then when you generate Haddock docs there could be an option to link to either local or external docs for other packages.
Cheers, Simon
I also tried editing ghc's package.conf file to place the other library's
HTML doc right into haddockHTMLs, replacing the pointer to my local copy.
Then Haddock says:
Warning: cannot use package phooey-0.1:
HTML directory http://darcs.haskell.org/packages/phooey/doc does not
exist.
and I don't get any links. The directory does exist, though of course not
on my machine. Why would Haddock care whether it can find a haddockHTMLs
directory?
- Conal
On 1/9/07, Conal Elliott
I fiddled with --read-interface to link to other-library docs at URLs. I'm trying to go through cabal and use --haddock-arg (a flag I recently added) to get additional flags to haddock. What seems to be happening is that --use-package wins over --read-interface for the same package, regardless of the order in which they're listed. The only way I can get the other-library links to point to web-documentation instead of local versions is to add --read-interface and *remove* the corresponding --use-package. Is that behavior what you intend? Given the use-package bias, I can't figure a way to get my web links via cabal. Using haddock manually would be quite a pain also, since I'm relying on cabal to preprocess all of my modules with -D__HADDOCK__ before passing them on to Haddock. The preprocessed versions come & go invisibly.
Are you aware of the use-package bias? Can you think of a work-around?
- Conal
On 12/15/06, Simon Marlow < simonmarhaskell@gmail.com> wrote:
Conal Elliott wrote:
My library uses others (including base & wxHaskell), and so references
to types & identifiers from those libraries show up in my Haddock docs. When I put the docs on the web, the links are bogus. How can I get those links to be web-accessible versions instead of my local versions?
Similarly, I want to package up my library so that others can build on top of it and have their published haddock documentation contain web-accessible pointers to my doc.
Have these issues been thought through? Thanks,
I'm not suggesting that this is a long-term solution, but Haddock does let you link to docs at an arbitrary URL, using the --read-interface flag. This isn't exposed through Cabal, but you can always find out the Haddock command that Cabal is executing and run a modified version by hand.
Ultimately I expect as part of the Hackage project we should automatically generate Haddock docs for all the packages and link them together. This needs some thought, perhaps it's something we can talk about at Hac.
Another thing we could consider doing is putting a public Haddock URL in the .cabal file, and propagating this into the package configuration. Then when you generate Haddock docs there could be an option to link to either local or external docs for other packages.
Cheers, Simon
participants (2)
-
Conal Elliott -
Simon Marlow