feat: documentation with sphinx

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: next/conf.py
+
+python:
+  install:
+  - requirements: next/requirements.txt

next/.gitignore

@@ -0,0 +1,3 @@
+_build
+*.mo
+__pycache__

next/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

next/README

@@ -0,0 +1,46 @@
+# (WIP) Next gen moonbit-docs
+
+A new MoonBit docs framework based on Sphinx.
+
+## Develop
+
+### Install
+
+```bash
+python3 -m venv .env
+source .env/bin/activate
+pip install -r requirements.txt
+```
+
+For building PDF using Latex, `latexmk` needs to be installed:
+- MacOS: 
+    - install [Mactex](https://www.tug.org/mactex/)
+    - install `latexmk` using TeX Live Utility
+
+### Build
+
+```bash
+make html
+python3 -m http.server -d _build/html
+```
+
+For Chinese version:
+
+```bash
+make -e SPHINXOPTS="-D language='zh_CN'" html
+python3 -m http.server -d _build/html
+```
+
+For PDF:
+
+```bash
+PATH=$PATH:/usr/local/texlive/2024/bin/universal-darwin/ make latexpdf
+open ./_build/latex/moonbitdocument.pdf
+```
+
+### Update translation template
+
+```bash
+make gettext
+sphinx-intl update -p _build/gettext -l zh_CN
+```

next/_ext/lexer.py

@@ -0,0 +1,37 @@
+from pygments.lexer import RegexLexer, words
+import pygments.token as token
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_lexer("moonbit", MoonBitLexer)
+    app.add_lexer("mbt", MoonBitLexer)
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
+
+class MoonBitLexer(RegexLexer):
+    name = "MoonBit"
+
+    tokens = {
+        'root': [
+            (r"//.*$", token.Comment),
+            (r"#\|.*$", token.String),
+            (r"\$\|.*$", token.String),
+            (r"\'.*\'", token.Literal),
+            (r"\"((\\\")|[^\"])*\"", token.String),
+            (r"-?\d+(.\d+)?", token.Number),
+            (words(('type', 'type!', 'enum', 'struct', 'trait'), suffix="\s"), token.Keyword),
+            (words(('fn', 'if', 'else', 'while', 'for', 'loop', 'match', 'let', 'mut', 'impl', 'with', 'derive'), suffix="\s"), token.Keyword),
+            (words(('return', 'break', 'continue'), suffix="\s"), token.Keyword),
+            (words(('try', 'catch', 'raise'), suffix="[\s{]"), token.Keyword),
+            (words(('pub', 'priv', 'pub\\(all\\)', 'pub\\(readonly\\)', 'pub\\(open\\)', 'test'), suffix="\s"), token.Keyword),
+            (words(('true', 'false'), suffix='[?!,\\)\s]'), token.Keyword),
+            (words(('Array', 'FixedArray', 'Int', 'Int64', 'UInt', 'UInt64', 'Option', 'Result', 'Byte', 'Bool', 'Unit', 'String', 'Show', 'Eq', 'Self'), suffix='[?!,\\)\s]'), token.Keyword),
+            (r"(=>)|(\|>)|(->)|(<<)|(>>)|(==)|(&&)|(\|\|)|[\(\)\{\}\[\]:,\.=+\-*/%!?~<>;@&\|]", token.Punctuation),
+            (r"[a-zA-Z_][a-zA-Z0-9_]*", token.Name),
+            (r"[\s]", token.Whitespace),
+        ]
+    }

next/conf.py

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'MoonBit Document'
+copyright = '2024, International Digital Economy Academy'
+author = 'International Digital Economy Academy'
+release = 'v0.1.20241125'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+import sys
+from pathlib import Path
+sys.path.append(str(Path("_ext").resolve()))
+
+extensions = ['myst_parser', 'lexer']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', ".env", '.venv', "README"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+
+# -- Options for LaTeX output ------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output
+latex_engine = 'xelatex'
+latex_elements = {
+    'preamble': r"\usepackage{xeCJK}",
+    'fvset': "\\fvset{formatcom={\\CJKsetecglue{}}}" # avoid having spaces around text in code blocks
+}
+
+# -- Options for myst_parser -------------------------------------------------
+myst_heading_anchors = 3
+
+# -- Options for gettext -----------------------------------------------------
+gettext_additional_targets = ["literal-block"]

next/index.md

@@ -0,0 +1,20 @@
+# MoonBit Documentation
+
+MoonBit is an end-to-end programming language toolchain for cloud and edge computing using WebAssembly.
+
+The IDE environment is available at [https://try.moonbitlang.com](https://try.moonbitlang.com) without any installation; it does not reply on any server either.
+
+**Get started**
+
+- [Tutorials](./tutorial/index.md): Follow tutorials to start your journey
+
+- [Language](./language/index.md): Introduction to detailed language specifications
+
+- [Toolchains](./toolchain/index.md): Introduction to all the toolchains making developing MoonBit a unique experience.
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents:
+language/index
+tutorial/index
+toolchain/index