doc(moonbit): add MoonBit explanation

[peter-jerry-ye]

This pull request adds documentation for MoonBit language support in the WebAssembly component model docs.

[vados-cosmonic]

Hey @peter-jerry-ye thanks for submitting this! We're having the SIG Docs meeting in roughly 5 hours and we're planning to discuss this PR!

Please feel free to drop by if you'd like:
https://github.com/bytecodealliance/meetings/tree/main/SIG-Documentation

[vados-cosmonic]

Hey @peter-jerry-ye so after some discussion given the maintenance burden and lack of experience of current maintainers with MoonBit, it's probably best to introduce a new page for new languages that support the component model.

On that new page, we can link out to MoonBit hosted documentation that follows the spirit of the guide. Would you mind updating this PR with that in mind? I can also help with some of the restructuring if you'd like.

[kate-goldenring]

@peter-jerry-ye I have put up a PR for a page to document more languages that support the component model: #308. What do you think? Would you be willing to move this documentation to MoonBit's docs and then you can create a new PR to the other-languages.md page and link to those docs from there? Thank you for all your work thus far -- we are excited to see MoonBit supporting the component model!

[itowlson]

@vados-cosmonic While I totally appreciate the maintenance concerns about including a language that the book maintainers aren't familiar with, I want to flag that one of the motivations for the book was current-ish documentation linking out to other documentation that had since become stale. So you never knew what was current - or whether anything you were looking at was current, or whether there was a current thing to look at; and if things didn't work, you never knew if this was "Ivan messed up" or "there's an error in the docs" or "oh those docs don't apply any more, we've not done it that way for months."

Having things in the book provides at least some opportunity to review them as the Component Model evolves. If things seem like they no longer work, and no maintainer can be found, we can remove the stale content or put a warning banner on it. Of course this does require at least enough understanding to spot if something looks stale, or to test it, and I appreciate that when a language has limited reach this can be hard for the book maintainers to do (at least with C we can have a sense that such-and-such might be impacted even if we lack the knowledge to update it ourselves).

So... I don't have a solution, but I just reckon it's worth pondering how we can minimise the "docs are stale" / "docs go out of sync" risk alongside the "book team does not know how to maintain content" risk.

(Apologies if this was already covered off at the SIG meeting - I'm sure I'm not the only person with this concern!)

[peter-jerry-ye]

Hi @vados-cosmonic thank you for your suggestion. I totally understand the concern about adding an pre-mature language to the document.

With that said, I wonder if we could at least have the documentation hosted on this site within a section under the other language, like 6.9.1 MoonBit? We may add explicit banner about the situation, and we can also help to maintain the document.

[vados-cosmonic]

Hey @itowlson a bit late here but great call out! This is exactly where we landed during the meeting so I think we're aligned there!

@peter-jerry-ye thanks for understanding!
Yeah, so during the meeting we discussed something like only taking on documentation if we were sure maintainers were available (the main worry being that maintenance would be a burden). Unfortunately, we just don't have any agreed upon process for this in place for this yet.

There are other languages like Grain that aren't listed at all (but are also WebAssembly focused), but we want to make a consistent policy first before we take on hosting the actual documentation directly.

That said, we're happy to link out to your existing documentation (and it would be fantastic if it was similar to the starting guide as you have written in this PR)!

[kate-goldenring]

@vados-cosmonic @itowlson @peter-jerry-ye I have been thinking about this more and if wit-bindgen has support for moonbit AND maintainers such as @peter-jerry-ye are committed to maintaining the documentation, then i think it is fair to add the docs to the component-docs and host them here.

[vados-cosmonic]

Welp I'm certainly not against it with a committed maintainer! @itowlson what do you think?

That said, @peter-jerry-ye we're in the process of comitting code that powers the examples to repo, so would you mind adding that? Ideally, code listing in the docs are using file references to interpolate like this.

[peter-jerry-ye]

@kate-goldenring Thank you for your proposal. I'm fine with both solutions. We do think supporting component model, both the tooling and the documentation, is important.

@vados-cosmonic I'll try to adjust the content.

As of the maintenance issue, I'm not sure if you would like to have a CI that automatically run through the process described in the tutorial, for example.

[vados-cosmonic]

@vados-cosmonic I'll try to adjust the content.

Thanks! 🙇

As of the maintenance issue, I'm not sure if you would like to have a CI that automatically run through the process described in the tutorial, for example.

Yup, that's exactly what we wan but we haven't taken the time to set that up yet!
We'll eventually get to it in the future, but the first step is to at least have the code in the repo :). If you can do that for this PR, someone else will come along and eventually wire up some CI that makes sure the examples always work.

We're probably not going to go as far as doing something like going through the code blocks in the markdown itself (though that would be super interesting), but we'll probably just put together some justfiles or some other way to build each individual example that we can re-run.

[peter-jerry-ye]

Hi @vados-cosmonic I have extracted the code to a separate directory like other programming languages. Let me know if there are other adjustments I need to do.

[vados-cosmonic]

Did a review, thanks for adding MoonBit, everything looks great so far!

[peter-jerry-ye]

@vados-cosmonic Thank you for your suggestions! Sorry that I didn't notice the difference between sh and console.

As of the highlighter, I need to confirm how mdBook supports custom highlighting.

[vados-cosmonic]

Ahh thank you for the note @peter-jerry-ye -- please ignore the highlighting for now, rust absolutely is fine for a best-effort pass!

[peter-jerry-ye]

I could follow pen-lang/pen#395 to add a custom js to highlight moonbit, but it seems that it would rerender all the code after adding the language definition. Does it worth it or should we borrow the highlighting from Rust for the moment?

[vados-cosmonic]

Yeah let's definitely just use rust for now -- please ignore those comments where I suggested moonbit!

[peter-jerry-ye]

Hi @vados-cosmonic I've update the content based on the suggestions. Is there anything else I could improve?

[vados-cosmonic]

LGTM 🚀

Thanks @peter-jerry-ye !

I'm going to batch these requested changes and get this merged.