Open ezyang opened 9 years ago
This is a fine place to report this. Honestly I have considered to just get rid of that site all together. Currently it mainly serves as a host for user documentation but if we do something about #338 then we can just use GitHub for that.
We can use GitHub pages, even if we stick with docbook. It can server arbitrary static HTML.
I'll actually just fix a few things on the page for now to point to the github as the central thing, and then let people sort out the rest. But the documentation certainly should be updated and hosted somewhere!
Ok, the page is now updated to point to github for all development work. Uploading new docs still needs to happen, or finding a new home for them if preferred...
Cabal and stack now use Read the Docs to serve their documentation. One feature of RtD that I find very useful is that users can easily switch between different versions of the documentation, e.g. https://docs.haskellstack.org/en/stable/README/ and https://docs.haskellstack.org/en/v1.2.0/README/.
Given that many haddock users don't use the latest version, I think that could be a useful feature. I haven't seen anything similar for GitHub Pages.
I have (or at least had and could probably get it again if I don't) access to haskell.org/haddock
; not sure if I can set up a redirect or something but anyway we just need someone eager to do the leg-work of porting it over to pages/readthedocs/whatever it is
If anyone needs access to the site, I'll help out. Or if it just ends up being a redirect I can put it in place...
we just need someone eager to do the leg-work of porting it over to pages/readthedocs/whatever it is
I'll have some time in mid February to do that if no one beats me to it!
So, I'm kind of ready to do the porting (to Read the Docs), but I'm split about which markup language to use:
If we go for Markdown we're limited to CommonMark which has subtle and not-so-subtle differences to GitHub flavored Markdown and e.g. doesn't support tables.
reStructedText is the more fully featured alternative that Read the Docs recommends for technical documentation but which I believe fewer contributors will be familiar with. GHC uses RST for its user's guide.
Any opinions / preferences?
+1 for RST. I don't think the unfamiliarity will be a problem, esp. since GHC and Cabal's users guides are written in RST.
I'm in favor of Markdown.
Skimming through the existing documentation, we don't use any tables. And if we would want to use them, inline HTML should still work, I guess.
Anyway, I'm not doing the work, so I'm not making the call.
Just wondering where this is at. These days, I download Haddock source and use sphinx to generate the docs rather than using the online reference, since http://haskell.org/haddock is now 3 years out of date. (Also since the sphinx docs are much nicer to look at).
The readthedocs version is here: http://haskell-haddock.readthedocs.io/en/latest/index.html. Could make the website point to that.
I updated the link as requested, since I have access and nobody else seemed to be getting around to it :-)
The website could still probably stand to be updated with regards to releases, etc.
Again, note anyone that's on the haddock team and wants to be given capabilities to edit the website, please just ask.
@gbaz Do you know how to update https://haskell-haddock.readthedocs.io/en/latest/index.html? It seems to be built against 76d0f9b90a7b2f65ae12e1ce5dd0552909493252, which is somewhat outdated. I think it would be nice to include updating this in the process for releasing a new Haddock version.
This isn't really the right place, but I'm not sure where else to report this. The Haddock website: https://www.haskell.org/haddock/ needs some updating: