Please fix documentation for you Hackage packages!
Greetings café, As some of you might have noticed recently, there seems to be quite a few packages with broken documentation on Hackage recently. If you are an owner of such package, please consider fixing it. There's a thread on cabal-devel about this if you're interested in details. Here's a list of packages uploaded since beginning of 2013 for which the documentation was broken as of yesterday: http://fuuzetsu.co.uk/misc/sorted.txt If your package is on that list, your documentation is broken. Only the most recent versions of packages were being considered. I outline how to fix your documentation (in most cases this means uploading it by hand) in a blog post I just published. Please refer to: http://fuuzetsu.co.uk/blog/posts/2014-01-06-Fix-your-Hackage-documentation.h... The post contains a link to as script which naively attempts to automate the burden of uploading the docs manually. If your package can't be built simply with ‘cabal configure && cabal build && cabal haddock --hyperlink-source’, you'll have to adapt it to your situation. Thanks. I hope to see fewer packages with broken documentation in the future. -- Mateusz K.
Is there any way you could tag that list with the author so that we can Ctrl+f ourselves? On Sun, Jan 5, 2014 at 8:37 PM, Mateusz Kowalczyk <fuuzetsu@fuuzetsu.co.uk>wrote:
Greetings café,
As some of you might have noticed recently, there seems to be quite a few packages with broken documentation on Hackage recently. If you are an owner of such package, please consider fixing it. There's a thread on cabal-devel about this if you're interested in details.
Here's a list of packages uploaded since beginning of 2013 for which the documentation was broken as of yesterday: http://fuuzetsu.co.uk/misc/sorted.txt
If your package is on that list, your documentation is broken. Only the most recent versions of packages were being considered.
I outline how to fix your documentation (in most cases this means uploading it by hand) in a blog post I just published. Please refer to:
http://fuuzetsu.co.uk/blog/posts/2014-01-06-Fix-your-Hackage-documentation.h...
The post contains a link to as script which naively attempts to automate the burden of uploading the docs manually. If your package can't be built simply with ‘cabal configure && cabal build && cabal haddock --hyperlink-source’, you'll have to adapt it to your situation.
Thanks. I hope to see fewer packages with broken documentation in the future. -- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
-- Clark. Key ID : 0x78099922 Fingerprint: B292 493C 51AE F3AB D016 DD04 E5E3 C36F 5534 F907
On 06/01/14 01:47, Clark Gaebel wrote:
Is there any way you could tag that list with the author so that we can Ctrl+f ourselves?
Not without fetching the data again. I can do it if you find it absolutely necessary but you'd have to wait. Do you want it? This is the third time in ~24 hours where I wish I simply saved the pages… -- Mateusz K.
Haha it's alright. I'll survive. I feel sorry for ekemett, bos, and friends, though. On Sun, Jan 5, 2014 at 8:50 PM, Mateusz Kowalczyk <fuuzetsu@fuuzetsu.co.uk>wrote:
On 06/01/14 01:47, Clark Gaebel wrote:
Is there any way you could tag that list with the author so that we can Ctrl+f ourselves?
Not without fetching the data again. I can do it if you find it absolutely necessary but you'd have to wait. Do you want it?
This is the third time in ~24 hours where I wish I simply saved the pages…
-- Mateusz K.
-- Clark. Key ID : 0x78099922 Fingerprint: B292 493C 51AE F3AB D016 DD04 E5E3 C36F 5534 F907
Here is the package <-> maintainer list. Hackage should have a feature for this. (Did this with the Hackage API: for p in `cat packages`; do echo -n "$p "; curl http://hackage.haskell.org/package/$p/uploader; echo; done) bindings-cctools BadiAbdulWahid bitcoin-rpc JanVornberger cctools-workqueue BadiAbdulWahid commsec-keyexchange ThomasDuBuisson CurryDB HideyukiTanaka egison SatoshiEgi FreeTypeGL EyalLotem hbro-contrib koral hoodle-core IanWooKim hoodle IanWooKim hOpenPGP ClintAdams hs-excelx MarkBaran hsimport DanielTrstenjak MagicHaskeller SusumuKatayama module-management DavidFox OpenVG StephenTetley OpenVGRaw StephenTetley python-pickle VoMinhThu tkyprof MitsutoshiAoe webkitgtk3 HamishMackenzie Yablog HiromiIshii yesod-markdown PatrickBrisbin free-theorems-counterexamples DanielSeidel gemstone CorbinSimpson haskell-openflow BrianBrooks hbro koral nettle-frp AndreasVoellmy satchmo JohannesWaldmann bogre-banana DavidEichmann FailureT MatthewFarkasDyck HGamer3D PeterAlthainz hois DavidEichmann l-bfgs-b GardSpreemann libsystemd-daemon CedricStaub lojbanXiragan YoshikuniJujo marxup JeanPhilippeBernardy PandocAgda PeterDivianszky Ref CarterSchonwald biophd DanFornika chuchu FelipeLessa clckwrks-theme-geo-bootstrap JeremyShaw halipeto PeterSimons hsc3-graphs RohanDrape ipopt-hs AdamVogt linear-algebra-cblas CarterSchonwald miniball GardSpreemann mount NicolaSquartini musicbrainz-email OliverCharles Obsidian JoelSvensson ois-input-manager GregHorn Range ThomasEding TrieMap LouisWasserman unpack-funcs LouisWasserman Win32-junction-point MichaelSteele zmcat LucasDiCioccio datalog TristanRavitch decepticons JoeQuinn hunit-rematch TomCrayford iptables-helpers EvgenyTarasov linux-blkid NicolaSquartini live-sequencer HenningThielemann llvm-base CarterSchonwald llvm-extra HenningThielemann llvm CarterSchonwald llvm-tf HenningThielemann noise TomBrow quickcheck-rematch TomCrayford simple-firewire VilleTirronen synthesizer-core HenningThielemann synthesizer-llvm HenningThielemann unordered-containers-rematch TomCrayford aeson-schema TimBaumann atom-msp430 DanielBuckmaster binding-wx GideonSireling embeddock-example TakayukiMuranushi equational-reasoning HiromiIshii graph-rewriting-gl JanRochel kontrakcja-templates MariuszRak padKONTROL FumiakiKinoshita posix-pty MerijnVerstraaten saltine JosephAbrahamson watcher NateSoares Win32-services-wrapper GaneshSittampalam z3 IagoAbal atomic-primops RyanNewton bindings-libzip SergeyAstanin nitro ErinDahlgren qhull-simple GardSpreemann terrahs SergioCosta yesod-vend KrzysztofSkrzetnicki Capabilities BaldurBlondal cloudfront-signer ChrisDornan data-store PetrPilar hemokit NiklasHambuechen heukarya HeChienTsai hidapi NiklasHambuechen Hs2lib TamarChristina io-manager MihaiMaruseac Konf GoktugKayaalp LibZip SergeyAstanin NXTDSL AlexanderThiemann parsek JeanPhilippeBernardy sifflet-lib GregoryWeber Win32-services MichaelSteele xkbcommon AukeBooij hat OlafChitil henet JohnEricson kqueue ErikHesselink memexml FlorianEggenhofer ncurses JohnMillikin parcom-lib TobiasDammers proj4-hs-bindings PavelPenev geni-gui EricKow goa ChrisDone hist-pl JakubWaszczuk hoopl HerbertValerioRiedel karakuri FumiakiKinoshita lvish RyanNewton mysql BryanOSullivan nanomsg DavidHimmelstrup sarasvati outoftune snaplet-rest TimothyJones accelerate-cuda TrevorMcDonell accelerate-fft TrevorMcDonell cci FacundoDominguez chatter RoganCreswick concraft JakubWaszczuk concraft-pl JakubWaszczuk crf-chain2-tiers JakubWaszczuk cuda TrevorMcDonell data-variant TobiasDammers DirectSound BalazsKomuves flowdock-api gabemc ftree ConalElliott gitlib-s3 JohnWiegley glib HamishMackenzie gloss-accelerate TrevorMcDonell gloss-raster-accelerate TrevorMcDonell GraphHammer-examples AlexanderVershilov gtksourceview3 HamishMackenzie HaLeX joaoSaraiva hmatrix AlbertoRuiz hpaco-lib TobiasDammers imagemagick AlexanderVershilov lambda-devs alios missing-py2 domdere nerf JakubWaszczuk parsestar MichalGajda persistent-redis PavelRyzhov reorderable AlexCole sgd JakubWaszczuk sorted JosephAbrahamson webkitgtk3-javascriptcore HamishMackenzie Win32-extras KidoTakahiro wraxml HenningThielemann ajhc KiwamuOkabe ALUT SvenPanne cufft RobEverest dirfiles HugoGomes DnaProteinAlignment ChristianHoener Dust-crypto BrandonWiley Dust BrandonWiley Dust-tools BrandonWiley easyrender PeterSelinger fay-dom AdamBergmark fay-jquery AdamBergmark fay AdamBergmark FModExRaw DimitriSabadie FormalGrammars ChristianHoener fpco-api ChrisDone ghcjs-dom HamishMackenzie gitlib-libgit2 JohnWiegley GrammarProducts ChristianHoener gstreamer HamishMackenzie gtk3-mac-integration HamishMackenzie gtk-mac-integration HamishMackenzie hfsevents LuiteStegeman hledger-lib SimonMichael hledger SimonMichael hledger-web SimonMichael holy-project yogsototh hopfield NiklasHambuechen hPushover WJWH hzk DiegoSouza ihaskell gibiansky jsc HamishMackenzie language-puppet SimonMarechal newsynth PeterSelinger nm ChrisDone pretty-show IavorDiatchki quickcheck-property-comb jfeltz resource-effect ClarkGaebel RNAdesign ChristianHoener scotty-fay hdgarrood SDL2-ttf OmerAgacan SFML-control AlfredoDiNapoli SFML AlfredoDiNapoli singletons RichardEisenberg snaplet-mysql-simple ibotty tempodb ParnellSpringmeyer UISF dwincort units RichardEisenberg valid-names JoelTaylor ViennaRNA-bindings ChristianHoener wai-handler-webkit MichaelSnoyman yesod-pure MichaelSnoyman yesod-static MichaelSnoyman yi-monokai MateuszKowalczyk zeromq3-haskell ToralfWittner zeromq4-haskell ToralfWittner
To be honest, I actively encourage people to *not* fix their package documentation manually. This is tedious, error-prone, and I bet there will be tons of packages then where the actual code and documentation will disagree (worse than no documentation at all), we're humans after all. Fixing Hackage is the way to go, not some guaranteed-to-fail crowd-sourcing... :-/
In some cases it actually makes sense. For example, my kqueue package is in the list above. It is a binding to a MacOS/BSD C library, and the hackage build bot runs on linux. So I should actually upload the documentation... Erik On Mon, Jan 6, 2014 at 4:35 PM, Sven Panne <svenpanne@gmail.com> wrote:
To be honest, I actively encourage people to *not* fix their package documentation manually. This is tedious, error-prone, and I bet there will be tons of packages then where the actual code and documentation will disagree (worse than no documentation at all), we're humans after all. Fixing Hackage is the way to go, not some guaranteed-to-fail crowd-sourcing... :-/ _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Yes, it does make a lot of sense in these cases. It is not tedious. This Python script automates it for you: https://gist.github.com/nh2/8284831 (The original block post also contains a minimal script.) Maybe we can add a command `cabal upload-docs` that does this? On Mon 06 Jan 2014 16:47:57 CET, Erik Hesselink wrote:
In some cases it actually makes sense. For example, my kqueue package is in the list above. It is a binding to a MacOS/BSD C library, and the hackage build bot runs on linux. So I should actually upload the documentation...
Erik
On Mon, Jan 6, 2014 at 4:35 PM, Sven Panne <svenpanne@gmail.com> wrote:
To be honest, I actively encourage people to *not* fix their package documentation manually. This is tedious, error-prone, and I bet there will be tons of packages then where the actual code and documentation will disagree (worse than no documentation at all), we're humans after all. Fixing Hackage is the way to go, not some guaranteed-to-fail crowd-sourcing... :-/ _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
2014/1/6 Niklas Hambüchen <mail@nh2.me>:
[...] It is not tedious. This Python script automates it for you: [...]
If you have to use a long Python script, it totally fulfills my definition of "tedious". :-} Another question is: Do the hyperlinks to other packages work when docs are uploaded like this? This is extremely important IMHO.
On 06/01/14 16:14, Sven Panne wrote:
2014/1/6 Niklas Hambüchen <mail@nh2.me>:
[...] It is not tedious. This Python script automates it for you: [...]
If you have to use a long Python script, it totally fulfills my definition of "tedious". :-}
Another question is: Do the hyperlinks to other packages work when docs are uploaded like this? This is extremely important IMHO. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
No, they don't. Someone pointed out to me yesterday that maybe something like ‘--html-location='//hackage.haskell.org/package/'’ would allow it to work but I have not tried yet. -- Mateusz K.
That's a nice script. I've forked it [0] and fixed two issues: the matching on Version is now case insensitive, and it uses --format instead of -H to also work on MacOS/BSD tar. Now my package has documentation! All the links in it are wrong, though. Some regex replace might be able to fix that. Erik [0] https://gist.github.com/hesselink/8285419 On Mon, Jan 6, 2014 at 4:55 PM, Niklas Hambüchen <mail@nh2.me> wrote:
Yes, it does make a lot of sense in these cases.
It is not tedious. This Python script automates it for you:
https://gist.github.com/nh2/8284831
(The original block post also contains a minimal script.)
Maybe we can add a command `cabal upload-docs` that does this?
On Mon 06 Jan 2014 16:47:57 CET, Erik Hesselink wrote:
In some cases it actually makes sense. For example, my kqueue package is in the list above. It is a binding to a MacOS/BSD C library, and the hackage build bot runs on linux. So I should actually upload the documentation...
Erik
On Mon, Jan 6, 2014 at 4:35 PM, Sven Panne <svenpanne@gmail.com> wrote:
To be honest, I actively encourage people to *not* fix their package documentation manually. This is tedious, error-prone, and I bet there will be tons of packages then where the actual code and documentation will disagree (worse than no documentation at all), we're humans after all. Fixing Hackage is the way to go, not some guaranteed-to-fail crowd-sourcing... :-/ _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
2014/1/6 Erik Hesselink <hesselink@gmail.com>:
In some cases it actually makes sense. For example, my kqueue package is in the list above. It is a binding to a MacOS/BSD C library, and the hackage build bot runs on linux. [...]
Good point. But why is it necessary that the package actually *builds* when generating the docs? I think parsing + type checking/inference should be enough, or did I miss something?
On Mon 06 Jan 2014 17:16:54 CET, Sven Panne wrote:
Good point. But why is it necessary that the package actually *builds* when generating the docs? I think parsing + type checking/inference should be enough, or did I miss something?
Haddock can't do it. The "Broken documentation on Hackage." thread explains it.
2014/1/6 Niklas Hambüchen <mail@nh2.me>:
Haddock can't do it. The "Broken documentation on Hackage." thread explains it.
That's not a good reason, it is just a technical accident and an artifact of how the documentation is currently built. My point is: To build the documentation, we should probably not build the package itself, this seems to be the source of most problems. Doxygen doesn't generate *.o files, either AFAIK...
On 6 Jan 2014, at 16:23, Sven Panne wrote:
2014/1/6 Niklas Hambüchen <mail@nh2.me>:
Haddock can't do it.
Doxygen doesn't generate *.o files, either AFAIK...
Ya! Haddock's insistence on actually compiling the module (rather than just generating documentation) was the source of one of our most puzzling bugs ever. (1) Compile library with ghc. (2) Generate docs with Haddock. (3) Link library. Who would ever suspect that the code got recompiled with different options in that middle step? Regards, Malcolm
Evil! This doesn't happen with cabal, does it? On Mon 06 Jan 2014 17:39:38 CET, Malcolm Wallace wrote:
On 6 Jan 2014, at 16:23, Sven Panne wrote:
2014/1/6 Niklas Hambüchen <mail@nh2.me>:
Haddock can't do it.
Doxygen doesn't generate *.o files, either AFAIK...
Ya! Haddock's insistence on actually compiling the module (rather than just generating documentation) was the source of one of our most puzzling bugs ever.
(1) Compile library with ghc. (2) Generate docs with Haddock. (3) Link library.
Who would ever suspect that the code got recompiled with different options in that middle step?
Regards, Malcolm _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
On 1/6/2014 11:39 AM, Malcolm Wallace wrote:
Doxygen doesn't generate *.o files, either AFAIK... Ya! Haddock's insistence on actually compiling the module (rather than just generating documentation) was the source of one of our most puzzling bugs ever.
(1) Compile library with ghc. (2) Generate docs with Haddock. (3) Link library.
Who would ever suspect that the code got recompiled with different options in that middle step?
You never know when you will want to have your documentation automatically generated by Template Haskell...
truth. I think theres a few libs that do this, though their names escape me right now. On Mon, Jan 6, 2014 at 4:40 PM, Joe Quinn <headprogrammingczar@gmail.com>wrote:
On 1/6/2014 11:39 AM, Malcolm Wallace wrote:
Doxygen doesn't generate *.o files, either AFAIK... Ya! Haddock's insistence on actually compiling the module (rather than just generating documentation) was the source of one of our most puzzling bugs ever.
(1) Compile library with ghc. (2) Generate docs with Haddock. (3) Link library.
Who would ever suspect that the code got recompiled with different options in that middle step?
You never know when you will want to have your documentation automatically generated by Template Haskell...
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Hmmm, what if some parts of the code are TemplateHaskell-generated using some macros defined in the same package? On 06 Jan 2014, at 20:23, Sven Panne <svenpanne@gmail.com> wrote:
2014/1/6 Niklas Hambüchen <mail@nh2.me>:
Haddock can't do it. The "Broken documentation on Hackage." thread explains it.
That's not a good reason, it is just a technical accident and an artifact of how the documentation is currently built. My point is: To build the documentation, we should probably not build the package itself, this seems to be the source of most problems. Doxygen doesn't generate *.o files, either AFAIK... _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
On Mon, Jan 6, 2014 at 8:47 AM, MigMit <miguelimo38@yandex.ru> wrote:
Hmmm, what if some parts of the code are TemplateHaskell-generated using some macros defined in the same package?
I'd be happy with it failing in that case. It would be better than what we have now! I tend to think this could also be fixed (in many situations) but we *don't need* a perfect solution. --Rogan
On 06 Jan 2014, at 20:23, Sven Panne <svenpanne@gmail.com> wrote:
2014/1/6 Niklas Hambüchen <mail@nh2.me>:
Haddock can't do it. The "Broken documentation on Hackage." thread explains it.
That's not a good reason, it is just a technical accident and an artifact of how the documentation is currently built. My point is: To build the documentation, we should probably not build the package itself, this seems to be the source of most problems. Doxygen doesn't generate *.o files, either AFAIK... _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Point being: we need more people to get involved in dev / admin of hackage and help with associated hackage infrastructure. On Monday, January 6, 2014, Rogan Creswick wrote:
On Mon, Jan 6, 2014 at 8:47 AM, MigMit <miguelimo38@yandex.ru<javascript:_e({}, 'cvml', 'miguelimo38@yandex.ru');>
wrote:
Hmmm, what if some parts of the code are TemplateHaskell-generated using some macros defined in the same package?
I'd be happy with it failing in that case. It would be better than what we have now!
I tend to think this could also be fixed (in many situations) but we *don't need* a perfect solution.
--Rogan
On 06 Jan 2014, at 20:23, Sven Panne <svenpanne@gmail.com<javascript:_e({}, 'cvml', 'svenpanne@gmail.com');>> wrote:
2014/1/6 Niklas Hambüchen <mail@nh2.me <javascript:_e({}, 'cvml', 'mail@nh2.me');>>:
Haddock can't do it. The "Broken documentation on Hackage." thread explains it.
That's not a good reason, it is just a technical accident and an artifact of how the documentation is currently built. My point is: To build the documentation, we should probably not build the package itself, this seems to be the source of most problems. Doxygen doesn't generate *.o files, either AFAIK... _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org <javascript:_e({}, 'cvml', 'Haskell-Cafe@haskell.org');> http://www.haskell.org/mailman/listinfo/haskell-cafe
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org <javascript:_e({}, 'cvml', 'Haskell-Cafe@haskell.org');> http://www.haskell.org/mailman/listinfo/haskell-cafe
On 06 Jan 2014, at 17:23, Sven Panne <svenpanne@gmail.com> wrote:
[…] To build the documentation, we should probably not build the package itself, this seems to be the source of most problems. Doxygen doesn't generate *.o files, either AFAIK…
Some packages that have bindings to foreign libraries are not built in hackage since *cabal* is rejecting them; otherwise ghc would be happy to build them and produce haddocks. Cabal rejects them since they list libraries in the extra-libraries or pkgconfig-depends field that are not found, but as long as header files are not needed in building the package, only the linking process would ultimately fail. If this check by cabal could be overridden with some flag, then we’d easily get more packages to build and have docs. Daniel
participants (11)
-
Carter Schonwald -
Clark Gaebel -
Daniel Gorín -
Erik Hesselink -
Joe Quinn -
Malcolm Wallace -
Mateusz Kowalczyk -
MigMit -
Niklas Hambüchen -
Rogan Creswick -
Sven Panne