Mateusz Kowalczyk | 6 Jan 02:37 2014
Picon

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.html

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.
Clark Gaebel | 6 Jan 02:47 2014
Picon
Picon

Re: Please fix documentation for you Hackage packages!

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 <at> 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.html

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 <at> 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
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Mateusz Kowalczyk | 6 Jan 02:50 2014
Picon

Re: Please fix documentation for you Hackage packages!

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.
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Clark Gaebel | 6 Jan 03:01 2014
Picon
Picon

Re: Please fix documentation for you Hackage packages!

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 <at> 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
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Niklas Hambüchen | 6 Jan 15:46 2014

Re: Please fix documentation for you Hackage packages!

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
Sven Panne | 6 Jan 16:35 2014
Picon

Re: Please fix documentation for you Hackage packages!

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... :-/
Erik Hesselink | 6 Jan 16:47 2014
Picon

Re: Please fix documentation for you Hackage packages!

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 <at> 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 <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
Niklas Hambüchen | 6 Jan 16:55 2014

Re: Please fix documentation for you Hackage packages!

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 <at> 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 <at> haskell.org
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
Sven Panne | 6 Jan 17:14 2014
Picon

Re: Please fix documentation for you Hackage packages!

2014/1/6 Niklas Hambüchen <mail <at> 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.
Mateusz Kowalczyk | 6 Jan 23:13 2014
Picon

Re: Please fix documentation for you Hackage packages!

On 06/01/14 16:14, Sven Panne wrote:
> 2014/1/6 Niklas Hambüchen <mail <at> 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 <at> 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.
Erik Hesselink | 6 Jan 17:34 2014
Picon

Re: Please fix documentation for you Hackage packages!

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 <at> 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 <at> 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 <at> haskell.org
>>> http://www.haskell.org/mailman/listinfo/haskell-cafe
Sven Panne | 6 Jan 17:16 2014
Picon

Re: Please fix documentation for you Hackage packages!

2014/1/6 Erik Hesselink <hesselink <at> 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?
Niklas Hambüchen | 6 Jan 17:18 2014

Re: Please fix documentation for you Hackage packages!

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.
Sven Panne | 6 Jan 17:23 2014
Picon

Re: Please fix documentation for you Hackage packages!

2014/1/6 Niklas Hambüchen <mail <at> 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...
Malcolm Wallace | 6 Jan 17:39 2014

Re: Please fix documentation for you Hackage packages!


On 6 Jan 2014, at 16:23, Sven Panne wrote:

> 2014/1/6 Niklas Hambüchen <mail <at> 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
Niklas Hambüchen | 6 Jan 17:40 2014

Re: Please fix documentation for you Hackage packages!

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 <at> 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 <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Joe Quinn | 6 Jan 22:40 2014
Picon

Re: Please fix documentation for you Hackage packages!

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...
Carter Schonwald | 6 Jan 23:12 2014
Picon

Re: Please fix documentation for you Hackage packages!

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 <at> 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 <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
MigMit | 6 Jan 17:47 2014
Picon

Re: Please fix documentation for you Hackage packages!

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 <at> gmail.com> wrote:

> 2014/1/6 Niklas Hambüchen <mail <at> 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 <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
Rogan Creswick | 6 Jan 20:02 2014
Picon

Re: Please fix documentation for you Hackage packages!

On Mon, Jan 6, 2014 at 8:47 AM, MigMit <miguelimo38 <at> 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 <at> gmail.com> wrote:

> 2014/1/6 Niklas Hambüchen <mail <at> 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 <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Carter Schonwald | 6 Jan 20:31 2014
Picon

Re: Please fix documentation for you Hackage packages!

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 <at> 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 <at> gmail.com> wrote:

> 2014/1/6 Niklas Hambüchen <mail <at> 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 <at> haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Daniel Gorín | 6 Jan 19:08 2014
Picon

Re: Please fix documentation for you Hackage packages!


On 06 Jan 2014, at 17:23, Sven Panne <svenpanne <at> 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
timmy tofu | 6 Jan 17:47 2014
Picon

Re: Please fix documentation for you Hackage packages!

With authors (no emails), quick and dirty:

http://lpaste.net/raw/98035

Date: Sun, 5 Jan 2014 20:47:27 -0500
From: Clark Gaebel <cgaebel <at> uwaterloo.ca>
To: Mateusz Kowalczyk <fuuzetsu <at> fuuzetsu.co.uk>
Cc: haskell-cafe <haskell-cafe <at> haskell.org>
Subject: Re: [Haskell-cafe] Please fix documentation for you Hackage
        packages!
Message-ID:
        <CA+aES6NVWY_EJKzpWSTap1b3BTEWVzh2=+qTchiCMeLgtjeFbw <at> mail.gmail.com>
Content-Type: text/plain; charset="utf-8"

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 <at> 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.html
>
> 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 <at> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20140105/61df048c/attachment-0001.html>
_______________________________________________
Haskell-Cafe mailing list
Haskell-Cafe <at> haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe

Gmane