search

haskell / haddock

Haskell Documentation Tool
www.haskell.org/haddock/
BSD 2-Clause "Simplified" License
361 stars 241 forks source link

Website needs updating #360

Open ezyang opened 9 years ago

ezyang commented 9 years ago

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:

Fuuzetsu commented 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.

sol commented 9 years ago

We can use GitHub pages, even if we stick with docbook. It can server arbitrary static HTML.

gbaz commented 7 years ago

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!

gbaz commented 7 years ago

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

sjakobi commented 7 years ago

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.

Fuuzetsu commented 7 years ago

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

gbaz commented 7 years ago

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

sjakobi commented 7 years ago

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!

sjakobi commented 7 years ago

So, I'm kind of ready to do the porting (to Read the Docs), but I'm split about which markup language to use:

Any opinions / preferences?

ezyang commented 7 years ago

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

sol commented 7 years ago

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.

jml commented 7 years ago

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

ntc2 commented 7 years ago

The readthedocs version is here: http://haskell-haddock.readthedocs.io/en/latest/index.html. Could make the website point to that.

gbaz commented 7 years ago

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.

harpocrates commented 5 years ago

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