I’m new to learning OCaml and also new to this forum.
I am really enjoying learning OCaml, but there’s a lot of quirks and weird things since I feel like a lot of things are in transition right now, but one thing that really bugged me was how outdated the docs on the standard library looked.
It has a sidebar to quickly navigate between modules and functions. Also has a search bar.
Its a little heavy right now since all the docs are basically downloaded to front-end, but it works for now. In the future, I may change it to be served from the server-side.
How it works right now is this:
I use lambdasoup to parse the original standard library
I use atd-gen to convert it into json
I use bs-json to read it back in on the front-end. (with a hack for compatibility)
I then use bucklescript-tea to display it.
I feel that I could rearrange the content better, but I’m still a bit confused on certain things and I’m still a bit confused on Functors and more advanced concepts. I’ll get to that a little later.
I think that the content itself could be improved, but as I’m a beginner, not really going to be working on that for now.
It’s neat! Docs were actually recently revamped and made very nice, but I must admit that made it even nicer (though this is a matter of taste, and there might be people who may not share my feelings). But I’m with a greedy interest here, will you share the source code?
nice! it would be even better imo if the Top entry in each top-level module in the register would be merged into the module heading, so that clicking e.g. on List directly shows something in the main panel.
The reason for the “Top” entry is so that you can look into other modules list of functions without losing your spot. Sometimes you want to just do a quick comparison with other modules function lists.
I did weigh the benefits of that design decision though. It certainly is quicker to have the top-level module name bring you to the module, but that’s only if you already know kind of what you are looking for. If you want to do more research, it may not be as beneficial.
I’m still not completely certain this way is better, but I’ll leave it like this for now unless a lot of other people want that changed too.
This is a fine thing. I’m not sure all the aesthetic choices are what I’d prefer but that’s a quibble. You might want to download the OCaml sources and look at how the docs now look in the trunk of the git repository, they’ve changed a bit, and you might want to do some pull requests. Note that some of what you are interested in might be accomplished by using odoc instead of ocamldoc for generating the stdlib docs.
Yea, I’m not expecting everyone to agree with aesthetic choices, but I just did it out of frustration of how the standard docs looked and worked. I still think regardless, it looks and works better than the official one, but its just something I wanted to share, if people want to use it or not, its ok.
I personally want mine to look better in places, but my biggest concern was the ability to easily navigate between modules/functions and have a search feature. I don’t want to spend too much time on it, (well, I already spent much more than I anticipated )
@ivg did mention the docs had changed, but I hadn’t seen that in the manual linked to official site. (Or I’m just too new). I didn’t know they were being changed in the trunk branch now. I’ll have to take a look at that.
I did think briefly about the ocaml generators for docs, but I didn’t really look at them. I just figured that they would be too complicated for me to understand since I’m new to the language. I also thought it may be harder to do what I wanted by trying to modify them to my use case, but after all the effort to do what I did, maybe I could have at least looked into them. Anyways, it was a good learning experience.
You are not the only person who would like the documentation to look better, and help in making the official stuff be more readable and modern is actively welcome I think. Several of us made the docs significantly better for 4.07 than they were for 4.06 (don’t laugh, they’re much better) and having them better still for 4.08 would be a very good thing.
It’s possible that’s true, but you can probably still contribute by helping to make the css they generate etc. better. Quite seriously, assistance making the docs more readable is very helpful. Do see if you can help make the official stuff easier to read!
You are not the only person who would like the documentation to look better… Several of us made the docs significantly better for 4.07 than they were for 4.06 (don’t laugh, they’re much better) and having them better still for 4.08 would be a very good thing.
I wasn’t aware of that. Sorry, I didn’t mean to offend, but I just wanted to make them better. Glad people are working on it!
It’s possible that’s true, but you can probably still contribute by helping to make the css they generate etc. better. Quite seriously, assistance making the docs more readable is very helpful . Do see if you can help make the official stuff easier to read!
Yea, maybe I’ll look into it. I do think that if more people are going to come over to the language, this is an important thing. I just feel that me being new to the community and language, contributing anything seems like overstepping my bounds.
I didn’t see anyone mentioning it yet, but odoc is the tool that will eventually be used for all library documentation, including the standard library. The odoc folks might appreciate your help in improving the tool further.
To be honest even the OCaml reference manual doesn’t use the all power of LaTeX and looks rather dull. At least syntax highlight and better formatting would improve the reading experience a lot.
@seadynamic8 I think the general message is, please do help if you have time. Just because you’re a beginner doesn’t mean you can’t make a difference in the usability of the documentation.
)