Summary: A few weeks ago Hackage stopped generating docs. I have a script that generates the docs, and also fixes some Haddock bugs.
Update: The Haddock documentation generators are running once again, but may be somewhat behind for a little while. A few weeks ago Hackage stopped generating documentation, so if you look at recently uploaded pages they tend to either lack docs, or have very alert maintainers who did a manual upload. I've packaged up my solution, which also fixes some pretty annoying Haddock bugs. Given that I can now get docs faster and better with my script, I'll probably keep using it even after Haddock on Hackage gets restarted.
How to use it
- You are likely to get better results if you always install the packages you use with documentation.
- Ensure you have
tar,curl,cpandcabalon your$PATH. cabal update && cabal install neil- Make a release, don't touch any other code, then make sure you are in the project directory.
neil docs --username=YourHackageUsername- Type in your Hackage password at the prompt.
And like that, your docs are online. To see an example of something that was generated with this process, look at Shake.
What I fixed
I automated the process using scripts originally taken from the lens library, supplemented with suggestions from Reddit. I then do a number of manual fixups.
- Haddock now makes cross-module links where it doesn't know what the target is default to types. Concretely, if I write
'Development.Shake.need'in Haddock it generates a link to#t:need, which doesn't exist, when it should be#v:need- I fix that. Update: fixed in Haddock 1.14 or above, as per this ticket.
- On Windows, if you use
CPPand multiline bird-tick (>) Haddock blocks you get a blank line between each line. I fix that. - If you follow some of the simpler scripts links outside your package won't work (or at least, didn't for me). I fix that.
The neil tool
The neil tool is my personal set of handy Haskell scripts. I make all my releases with it (neil sdist), and do lots of checks that my packages conform to my rules (neil check). I also use it for driving my Travis instances. It's in fairly regular flux. Until now, I've always kept it in Darcs/Git and never released it - it's personal stuff tuned to how I work.
You might also notice that neil provides a library. Don't use that, I intend to delete it in a few weeks. Update: library removed.
5 comments:
If you keep the library, even with a single getVersion or no-op function it will allow us to see what version of the executable is installed via cabal list.
Alan, I have no intention of giving a changelog or meaningful version numbers, so it probably won't be much use. Until yesterday, the package has been on version 0.0 for about 5 years... If lots of people end up using the docs target, it should probably be spun into a real project with real version numbers, and then that might make sense.
Nice utility, and it just works for me. It would be nice to be able to have a --dry-run mode (build all docs, but not upload them). I was too lazy to figure out how to upload docs to Hackage... Thanks!
Сергей: I tend to just not type my password so it pauses, use ps to figure out where the temp directory is, and grab it from there.
Neil: yes, I did the same, verified the generated docs just before entering the password.
Post a Comment