Merge pull request #139 from ml-in-barcelona/docs-v1

Docs: experiment with docsify
ml-in-barcelona · Feb 14, 2022 · 6c51372 · 6c51372
2 parents 3bcd576 + 696ccb4
commit 6c51372
Show file tree

Hide file tree

Showing 26 changed files with 207 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,9 @@
 
 # Created by https://www.gitignore.io/api/node
 
+### OS ###
+.DS_Store
+
 ### Node ###
 # Logs
 logs

diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,24 @@
+- Introduction
+
+  - [New to OCaml?](new_to_ocaml.md)
+  - [Quick start](quickstart.md)
+  - [Your first components](first_components.md)
+
+- Main concepts
+
+  - [Host (lowercase) components](host_components.md)
+  - [Composite (uppercase) components](composite_components.md)
+  - [Children](children.md)
+  - [Hooks](hooks.md)
+  - [Refs](refs.md)
+  - [Lists and keys](lists_and_keys.md)
+
+- Guides
+
+  - [Context](context.md)
+  - [Custom elements and data-* attributes](custom_elements.md)
+  - [Building with Dune and Js_of_ocaml](dune_jsoo.md)
+  - [Gen_js_api](gen_js_api.md)
+  - [Use JavaScript components](use_js_components.md)
+
+- [API](api.html)
diff --git a/docs/all_snippets.ml b/docs/all_snippets.ml
@@ -0,0 +1 @@
+include Basic
diff --git a/docs/api.html b/docs/api.html
diff --git a/docs/children.md b/docs/children.md
@@ -0,0 +1,3 @@
+# Children
+
+todo
diff --git a/docs/composite_components.md b/docs/composite_components.md
@@ -0,0 +1,3 @@
+# Composite (uppercase) components
+
+todo
diff --git a/docs/context.md b/docs/context.md
@@ -0,0 +1,3 @@
+# Context
+
+todo
diff --git a/docs/custom_elements.md b/docs/custom_elements.md
@@ -0,0 +1,3 @@
+# Custom elements
+
+todo
diff --git a/docs/dune b/docs/dune
@@ -0,0 +1,14 @@
+(include_subdirs unqualified)
+
+(executables
+ (names All_snippets)
+ (modes js)
+ (libraries js_of_ocaml react)
+ (preprocess
+  (pps jsoo_react_ppx)))
+
+(rule
+ (alias runtest)
+ (deps All_snippets.bc.js)
+ (action
+  (run echo "docs")))
diff --git a/docs/dune_jsoo.md b/docs/dune_jsoo.md
@@ -0,0 +1,3 @@
+# Building with Dune and Js_of_ocaml
+
+todo
diff --git a/docs/first_components.md b/docs/first_components.md
@@ -0,0 +1,7 @@
+# Your first components
+
+## A simple component
+
+Jsoo-react components are functions that take input data and returns what to display. The library provides a DSL that allows to create elements like `div`, or `p` with just plain OCaml functions. The uppercase component props are passed as labelled arguments, while lowercase components take an array of attributes.
+
+[filename](snippets/basic.ml ':include :type=code :fragment=demo')
diff --git a/docs/gen_js_api.md b/docs/gen_js_api.md
@@ -0,0 +1,3 @@
+# Gen_js_api
+
+todo
diff --git a/docs/hooks.md b/docs/hooks.md
@@ -0,0 +1,3 @@
+# Hooks
+
+todo
diff --git a/docs/host_components.md b/docs/host_components.md
@@ -0,0 +1,3 @@
+# Host (lowercase) components
+
+todo
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,41 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'jsoo-react',
+      repo: 'https://github.com/ml-in-barcelona/jsoo-react',
+      loadSidebar: true,
+      search: 'auto', // default
+
+      // complete configuration parameters
+      search: {
+        maxAge: 86400000, // Expiration time, the default one day
+        paths: 'auto',
+        placeholder: 'Type to search',
+        noData: 'No results',
+        // Headline depth, 1 - 6
+        depth: 6,
+        hideOtherSidebarContent: false, // whether or not to hide other sidebar content
+     }
+    }
+  </script>
+  <!-- Docsify v4 patched -->
+  <script src="//cdn.jsdelivr.net/npm/@jchavarri/[email protected]"></script>
+  <!-- <script src="docsify.js"></script> -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+  <script>
+    // //cdn.jsdelivr.net/npm/prismjs@1/components/prism-ocaml.min.js will write over `ocaml` property, but docsify expects `ml`
+    Prism.languages.ml={comment:{pattern:/\(\*[\s\S]*?\*\)/,greedy:!0},char:{pattern:/'(?:[^\\\r\n']|\\(?:.|[ox]?[0-9a-f]{1,3}))'/i,greedy:!0},string:[{pattern:/"(?:\\(?:[\s\S]|\r\n)|[^\\\r\n"])*"/,greedy:!0},{pattern:/\{([a-z_]*)\|[\s\S]*?\|\1\}/,greedy:!0}],number:[/\b(?:0b[01][01_]*|0o[0-7][0-7_]*)\b/i,/\b0x[a-f0-9][a-f0-9_]*(?:\.[a-f0-9_]*)?(?:p[+-]?\d[\d_]*)?(?!\w)/i,/\b\d[\d_]*(?:\.[\d_]*)?(?:e[+-]?\d[\d_]*)?(?!\w)/i],directive:{pattern:/\B#\w+/,alias:"property"},label:{pattern:/\B~\w+/,alias:"property"},"type-variable":{pattern:/\B'\w+/,alias:"function"},variant:{pattern:/`\w+/,alias:"symbol"},keyword:/\b(?:as|assert|begin|class|constraint|do|done|downto|else|end|exception|external|for|fun|function|functor|if|in|include|inherit|initializer|lazy|let|match|method|module|mutable|new|nonrec|object|of|open|private|rec|sig|struct|then|to|try|type|val|value|virtual|when|where|while|with)\b/,boolean:/\b(?:false|true)\b/,"operator-like-punctuation":{pattern:/\[[<>|]|[>|]\]|\{<|>\}/,alias:"punctuation"},operator:/\.[.~]|:[=>]|[=<>@^|&+\-*\/$%!?~][!$%&*+\-.\/:<=>?@^|~]*|\b(?:and|asr|land|lor|lsl|lsr|lxor|mod|or)\b/,punctuation:/;;|::|[(){}\[\].,:;#]|\b_\b/};
+  </script>
+</body>
+</html>
diff --git a/docs/lists_and_keys.md b/docs/lists_and_keys.md
@@ -0,0 +1,3 @@
+# Lists and keys
+
+todo
diff --git a/docs/new_to_ocaml.md b/docs/new_to_ocaml.md
@@ -0,0 +1,3 @@
+# New to OCaml?
+
+todo
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,31 @@
+# Quick start
+
+## New project
+
+For new projects, the best way to start is by cloning [the jsoo-react template](https://github.com/ml-in-barcelona/jsoo-react-template).
+
+## Existing project
+
+1. Install the `jsoo-react` package:
+
+    ```bash
+    opam pin add -y jsoo-react https://github.com/ml-in-barcelona/jsoo-react.git
+    ```
+
+2. Add `jsoo-react` library and ppx to [dune](https://dune.readthedocs.io/en/stable/) file of your executable JavaScript app:
+
+    ```dune
+    (executables
+    (names index)
+    (modes js)
+    (libraries jsoo-react.lib)
+    (preprocess
+      (pps jsoo-react.ppx)))
+    ```
+
+3. Provision React.js library
+
+    `jsoo-react` uses `require` to import React and ReactDOM. This means that you will likely need to use a bundler such as Webpack or rollup.js.
+
+    Note that at this moment, `jsoo-react` is compatible with **React 16.x**, so be sure to have the appropriate constraints in your `package.json`.
+
diff --git a/docs/readme.md b/docs/readme.md
@@ -0,0 +1,26 @@
+# jsoo-react
+
+> React.js in OCaml.
+
+## What it is
+
+Jsoo-react are the bindings to [React.js](reactjs.org/) for the [OCaml](https://ocaml.org/) language, in particular, for [Js_of_ocaml](https://ocsigen.org/js_of_ocaml/latest/manual/overview), a compiler that transforms OCaml bytecode into JavaScript.
+
+Jsoo-react allows to write components in a way that is familiar for both OCaml and JavaScript developers.
+
+See the [Quick start](quickstart.md) guide for more details.
+
+## Features
+
+- Support for both Reason syntax and OCaml syntax
+- Integrated with Js_of_ocaml and the OCaml ecosystem
+- Optimized output, small footprint on JavaScript bundles
+- Heavily tested
+
+## Examples
+
+Check out the [Real World Example App](https://github.com/jchavarri/jsoo-react-realworld-example-app) to see Jsoo-react in use.
+
+## Community
+
+Users and the development team usually hang out in the [Reason](https://discord.gg/reasonml) and [OCaml](https://discord.gg/cCYQbqN) Discord servers. If you have specific questions, don't hesitate to start a [discussion on the GitHub repo](https://github.com/ml-in-barcelona/jsoo-react/discussions).
diff --git a/docs/refs.md b/docs/refs.md
@@ -0,0 +1,3 @@
+# Refs
+
+todo
diff --git a/docs/snippets/.ocamlformat b/docs/snippets/.ocamlformat
@@ -0,0 +1 @@
+profile = ocamlformat
diff --git a/docs/snippets/basic.ml b/docs/snippets/basic.ml
@@ -0,0 +1,13 @@
+(* [demo] *)
+open React.Dom.Dsl
+open Html
+
+module Hello_message = struct
+  let%component make ~name = div [||] [React.string ("Hello " ^ name)]
+end
+
+let () =
+  React.Dom.render_to_element_with_id
+    (Hello_message.make ~name:"Taylor" ())
+    "hello-example"
+(* [demo] *)
diff --git a/docs/use_js_components.md b/docs/use_js_components.md
@@ -0,0 +1,3 @@
+# Use JavaScript components
+
+todo
diff --git a/lib/core.mli b/lib/core.mli
@@ -1,10 +1,15 @@
+(** A React element *)
 type element = private Ojs.t
 
 val element_of_js : Ojs.t -> element
+(** Conversion function for gen_js_api *)
 
 val element_to_js : element -> Ojs.t
+(** Conversion function for gen_js_api *)
 
-val null : element [@@js.custom let null = Ojs.null]
+val null : element
+  [@@js.custom let null = Ojs.null]
+(** A React element that will render the [null] value *)
 
 val string : string -> element [@@js.cast]
 

diff --git a/test/dune b/test/dune
@@ -21,3 +21,5 @@
   (source_tree node_modules))
  (action
   (run node test_jsoo_react.bc.js)))
+
+(data_only_dirs node_modules)