As discussed in the OCAML Documentation Open Thread, there are quite a few improvements we could make to the ocaml.org site. This is a thread for such discussions and observations: what we want the site to to be, what we could improve, possible process improvements, etc.
In this spirit, I’ve put a couple of pull requests up for the site today.
Also, apparently, at the moment, we cannot build the site under >=4.06 until this pull request is dealt with to safe-string MPP.
@perry, did you have any issues with -package netstring, which is a requirement? It’s from netmulticore, but apparently it’s not installed correctly by opam?
It would be really really good to have the site on opam.
See this issue — I haven’t gotten that far yet. If I’m about to hit that, perhaps we should package it up for opam? It would be good to have it as easy as possible for people to work on ocaml.org which implies that everything should be packaged and should run under the latest OCaml.
I’ve got the site building now, but only on 4.05.0. On 4.06.0, I pinned mpp’s fix and submitted a constraint change for opamfu, but after downloading a bunch of stuff, I get a segmentation fault.
BTW, building the site takes a ridiculous amount of time, possibly because of all the downloading it does.
Normally, this is cached for about 1h. Most of the time is spent on running the code snippets I think. In any case, we did our best with what was available at the time. It may now be appropriate to revisit these decisions if some volunteers are willing to contribute to the necessary work.
Just to make it clear, none of my criticism is targeted at the people who built the site. You guys did a great job, and you got stuff done. When I use a word like ‘ridiculous’, that’s exaggerated for effect. I’m coming from the perspective of, “how do we improve things given what we have” and “how do we strategically use the resources we have as a community to make the most impact”.
Now that MPP in opam works with 4.06, I was able to build the site!
The time it takes to do a full rebuild is indeed probably an issue — it was over half an hour on my laptop. Maybe there’s a way to break up which portions are built so that if someone is just working on one section it isn’t necessary to rebuild everything at once?
I also got a lot of warnings while it was building, and not quite everything seems correct when I view the HTML locally — should I file tickets for these issues?
Yes, at least for the more important ones. Note that, as said above, @ashish and I would like to revisit the decisions made for building the site but that also requires help from the community to perform the needed work.
Naturally. I think the most strategic changes are those that make it easier for community members to pitch in of course — this creates a positive feedback loop. This is part of why I’m trying to do things like building the web site, so I can see what the pain points are preventing people from helping.