Hello folks! We’ve ported the new ReScript docs to the old Reason and ML syntax, available in the v8.0.0 manual:
We’ve also temporarily removed the built-in ReasonReact docs and directed the relevant links to the external ReasonReact docs at reasonml.github.io/reason-react. We might undo this decision later when we refocus on ReasonReact docs.
Have a nice day!
Fantastic. This is much appreciated. Some UX improvements that make things clearer (I had to look where to find it even though I saw the screenshots).
Hey!
Version switching for the Api docs section will be available soon. The url schema will also be changed, so that the manual and api are tracked under one version, which will allow more consistent linking between manual / api content without leaving the version subpath.
To be clear, the latest / v8.0.0 docs will only marginally change content wise, so we didn’t go with a fully blown syntax toggling feature due to time constraints and instead branched to two different doc versions instead.
To give more context on why we did this: Syntax shows up in the docs in very different markups and contexts (table cells, code blocks, api signature blocks,…) which means we’d need to spend a lot of time fine tuning the syntax convertion mechanism to be able to reliably change syntax dynamically (and we couldn’t really guarantee if every snippet transforms into a human readable form). The experience would probably be flaky, so we hope that for now ppl are willing to use the v8.0.0 section for their Reason needs until our IDE plugins are ready.
I think this should be good enough and will help us freeing up some of our time to work on other urgent features such as full doc search as well.
Hope this helps!
I’m not sure I’m understanding.
Why is automatic conversion needed? Why not just keep the docs on the same git repo as the code and just point to the different versions as they were when the tag was created?
Fair point, but kinda unrelated to our problem. We are currently curating the most up to date resources in ReScript syntax. Whenever we’d change / add documentation, we’d need to manually maintain the Reason representation for each example as well. So it really doesn’t matter if those files are either versioned / deployed via git branches or part of the same directory hierarchy.
That’s why I mentioned the automatic conversion. For the manual itself it wouldn’t be too much of a deal, but for the API docs it’s actually non-trivial, since those are inhabiting hundreds of codeblocks / signatures that can’t be easily handled without some extra tooling that doesn’t exist yet.
Update: API docs version toggle now available:
Great! It would be great to have 8.0.0 selected by default until the new syntax is stable and ready for prod?
I hear the editor support is still way out (a few months) and the current syntax still ships with some major bugs that are getting identified (like deleting code when reformatting). Very understandable for an experimental syntax. But probably good to only have the living on the edge syntax for people that are experimenting (and under an explicit opt-in), and have a stable workflow for most other people.
Thank you so much for doing this!
