rescript-association / reasonml.org Goto Github PK

As reflected by the design here

Text Boxes

• <WarnBox>
• <InfoBox>
• <UrlBox>

blockquote

ImageBox

Note how the image escapes the layout on both sites. Should be able to display the reference text / alt text.

We will need to figure out a good index structure to efficiently look for all the necessary data.
Would be great to be able to classify by Belt and JS equivalent function.

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/hash-map.mdx

https://bucklescript.github.io/bucklescript/api/Belt_MutableSet.html
https://bucklescript.github.io/bucklescript/api/Belt_MutableSetInt.html
https://bucklescript.github.io/bucklescript/api/Belt_MutableSetString.html

I just noticed that pages don't have a title. I am willing to implement this feature.

We transferred the names and type definitions, but explanations and examples are missing.

Current work: https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/list.mdx

Belt List docs: https://bucklescript.github.io/bucklescript/api/Belt_List.html

Please comment on this issue if you would like to pick it up.

BuckleScript needs a dedicated section for all its external decorators, such as [@bs.module], with proper examples and more thorough explanation on its use-cases.

bs-blabla is probably the most complete documentation on all available decorators so far, so it would be great to process the material in a way so it's easy to navigate on the docs. (I asked the original author for permission, not sure if he still needs to add a license file though)

How to do this?
All bucklescript related information lives in the pages/docs/reason-compiler/latest directory. The navigation can be extended in layouts/ReasonCompilerDocsLayout.re.

This includes all submodules inside it.
See: https://bucklescript.github.io/bucklescript/api/Js.html

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/option.mdx

As discussed here, it is a good idea to have a list of reserved keywords.

It would also be interesting to discuss certain syntax desugaring (such as __x for first pipe placeholder and type_ vs. type conversion in object attributes).

There has been some more activity on both repos lately.
This includes all changes starting from January 2020

reasonml.github.io history:
https://github.com/reasonml/reasonml.github.io/commits/source

bucklescript.github.io history:
https://github.com/BuckleScript/bucklescript.github.io/commits/source

(No activity on the ReasonReact docs so far)

We transferred the names and type definitions, but explanations and examples are missing.

Current work: https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/hash-map.mdx

Belt HashMap docs: https://bucklescript.github.io/bucklescript/api/Belt.HashMap.html

Please comment on this issue if you would like to pick it up.

For some reason some code blocks have a scrollbar, others don't.

The examples all work and pass the tests again, but there is some boilerplate in many of them.

Especially the

module IntCmp =
  Belt.Id.MakeComparable({
    type t = int;
    let cmp = Pervasives.compare;
  });

in Set or Map examples makes the whole thing harder to read. What if we had some prelude which gets copied implicitly to every example where it is needed?

The examples could have 2 viewing modes:

• a concise one
• a complete one

Noticed it while I briefly couldn't use the Mouse

In Chrome it works fine

After #28 is merged, we should think about fixing the examples.
Most of them are straightforward, such as correcting map to Belt.Array.map etc.

The currently open Module looks exactly like the other menu entries. I noticed this confused beginners who aren't that familiar with Belt.
I believe it would help if both would look a bit different or there would be some kind of visual horizontal rule.

Rust uses this:

We transferred the names and type definitions, but explanations and examples are missing.

Current work: https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/hash-set-string.mdx

Belt HashSet Int docs: https://bucklescript.github.io/bucklescript/api/Belt_HashSetString.html

Please comment on this issue if you would like to pick it up.

Need to coordinate with @cristianoc regarding structure and syncing process, but I guess just splitting up the README by headlines should be fine.

https://github.com/cristianoc/genType

Currently long signatures don't fit and there is a horizontal scrollbar. For once sometimes it's not obvious that I can scroll and in general it's not a nice experience when trying to grasp the whole functions.

For wider screens to we really need to cut them off?
For smaller screens would could wrap them to the next line?
Any other ideas?

I would like to define how the ideal documentation structure, voice and tone for a module & its functions look like.

Ideally this results in a very crisp guide on how to do this. Once this is defined we can focus on aligning all of them. (Aligning them already came up 4 times or so).

If you have ideas or good examples please chime in here as well.

One example for a guide I like is this one: https://package.elm-lang.org/help/documentation-format

Currently the click area is the size of the text. The smaller the text the harder it is to reach it easily.

By applying display: block to the links the click area would be way larger.

What do you think @bettistein @ryyppy?

We transferred the names and type definitions, but explanations and examples are missing.

Current work: https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/option.mdx

Belt Option docs: https://bucklescript.github.io/bucklescript/api/Belt_Option.html

Please comment on this issue if you would like to pick it up.

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/hash-set.mdx

I noticed that to get to the bottom of the sidebar on Firefox I have to scroll down to the bottom of the main page. You can see how the bottom of the sidebar is cropped in this screenshot from the 13" screen of my old macbook air. Works as intended on Chrome. Maybe something to keep in mind during #84 :)

@bettistein requires content to be able to create a custom design and illustrations for the landing page.

This discussion has some good points that also resonate with our previous ideas, let's see where this goes.

We transferred the names and type definitions, but explanations and examples are missing.

Current work: https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/hash-set-int.mdx

Belt HashSet Int docs: https://bucklescript.github.io/bucklescript/api/Belt_HashSetInt.html

Please comment on this issue if you would like to pick it up.

To ensure a given quality of the examples, the example-code inside the readmes shall be verified and tested automatically. (freely quoted from reasonml.org)

Let's use this issue to plan and track the process of this task.

1. How should the process to publish and test examples look like?
2. Do you know some tools we could use to achieve this task?

https://bucklescript.github.io/bucklescript/api/Belt_SortArrayInt.html
https://bucklescript.github.io/bucklescript/api/Belt_SortArrayString.html

User @johnridesabike just announced his reason news aggregator in Discord.

https://github.com/johnridesabike/reason-planet
It currently aggregates blogposts from

• https://reasonml.github.io/blog/
• https://reasonml.github.io/reason-react/blog/
• https://bucklescript.github.io/blog/
• https://esy.sh/blog/

We think it would be an ideal fit for reasonml.org, as this site already aims to be the entry point for reason newcomers.

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/list.mdx

https://bucklescript.github.io/bucklescript/api/Belt_MapInt.html
https://bucklescript.github.io/bucklescript/api/Belt_MapString.html
https://bucklescript.github.io/bucklescript/api/Belt_MapDict.html

Currently, when I moved from the top page to the API page, the search input position moves from right to left. This is little uncomfortable.

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/float.mdx

https://bucklescript.github.io/bucklescript/api/Belt.MutableMap.html
https://bucklescript.github.io/bucklescript/api/Belt_MutableMapInt.html
https://bucklescript.github.io/bucklescript/api/Belt_MutableMapString.html

https://bucklescript.github.io/bucklescript/api/Belt_Map.html

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/int.mdx

screenshot from reasonml.org:

and from reasonml.github.io:

Also I was able to trigger a 404 error when clicking on the here I thought adef6f3 helped to prevent that.

Currently we are only exposing a navigation for the Belt docs, but we would need some generalized navigation page to expose the Js and Node module as well.

This is probably a more complex issue, since we need to abstract some layout from the BeltDocsLayout module first.

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/id.mdx

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/range.mdx

We transferred the names and type definitions, but explanations and examples are missing.

Current work: https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/set.mdx

Belt Set docs: https://bucklescript.github.io/bucklescript/api/Belt.Set.html

Please comment on this issue if you would like to pick it up.

The ocaml-manual is the official handbook for using OCaml. It fully describes all features and syntax elements and is highly valuable for explaining complex mechanisms, such as GADTs or polymorphic variants.

This is an ambitious task, I actually post it here so we don't forget about it. It's also a quite isolated task which will hopefully not interfere with our current work, if you feel like experimenting and have any progress, please let us know in this issue, so we can keep track of it.

What needs to be done?

• Revive rtop with the most recent Reason version (\cc @jordwalke)
• Create a mirror of the ocaml-manual repository
• Use the ocaml manual build system to use rtop instead of utop to output Reason formatted signatures
• Add refmt for reformatting ml codesnippets in the build system
• Make the build system expose markdown / json instead of html

Especially the markdown rendering will be useful, since we will then be able to commit the generated markdown output in our existing infrastructure (also makes it easier for us to style).

We want a first rough stylistic review for the Belt documentation to make it easier on the eyes early on.

Goals:

• Search component
• Module API Layout (such as Belt.List)
• Prose Layout (such as Belt Overview)
• Sidebar navigation (mobile support?)

The design should be provided via public URL.

Not sure where to put this, but it would be great to keep track of the Belt version somewhere visible (maybe header?). I was thinking of retrieving the bs-platform version from our package.json for now.

We need a CONTRIBUTING.md which contains following information:

How to give feedback for better documentation:
This includes feedback about everything related to Reason / BuckleScript / ReasonReact etc. Missing pieces of documentation, unclear instructions on using specific tools.

Example: I couldn't find any documentation on how to set an aria label in ReasonReact

How to report issues with existing documentation
In cases where documentation is wrong, broken, out-of-date etc.

How to contribute documentation
Especially with some information on what the current focus is, where help is needed, how to get an issue assigned etc.

Right now we didn't bother implementing the logic for sluggifying the hrefs and just used the ugly %20 / upper- and lowercased versions of title anchor links.

Example:

## Hello World

should translate to #hello-world instead of #Hello%20World

Things to do:

• Add github-slugger logic to Markdown.re's <Anchor> component

Make sure:

• That multiple titles with the same content are actually suffixed with a increasing number (e.g. #using and #using-1)
• That the sidebars refer to the same sluggified anchor (sync logic between markdown rendering and TOC generation)

https://github.com/reason-association/reasonml.org/blob/master/pages/belt_docs/result.mdx