From 04df59782ae2036ced19e2de672b301870072eaa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Loi=CC=88c=20Correnson?= <loic.correnson@cea.fr>
Date: Wed, 13 May 2020 16:55:59 +0200
Subject: [PATCH] [dome/typedoc] template for guides
---
ivette/Makefile | 12 ++
ivette/doc/pandoc/href.lua | 4 +
ivette/doc/pandoc/template.html | 87 ++++++++++
ivette/src/dome/doc/guides/application.md | 121 +++++++++++++
ivette/src/dome/doc/guides/development.md | 203 ++++++++++++++++++++++
ivette/src/dome/doc/guides/dome.md | 28 +++
ivette/src/dome/doc/guides/glossary.md | 32 ++++
ivette/src/dome/doc/guides/hooks.md | 22 +++
ivette/src/dome/doc/guides/hotreload.md | 47 +++++
ivette/src/dome/doc/guides/icons.md | 3 +
ivette/src/dome/doc/guides/quickstart.md | 26 +++
ivette/src/dome/doc/guides/styling.md | 65 +++++++
12 files changed, 650 insertions(+)
create mode 100644 ivette/doc/pandoc/href.lua
create mode 100644 ivette/doc/pandoc/template.html
create mode 100644 ivette/src/dome/doc/guides/application.md
create mode 100644 ivette/src/dome/doc/guides/development.md
create mode 100644 ivette/src/dome/doc/guides/dome.md
create mode 100644 ivette/src/dome/doc/guides/glossary.md
create mode 100644 ivette/src/dome/doc/guides/hooks.md
create mode 100644 ivette/src/dome/doc/guides/hotreload.md
create mode 100644 ivette/src/dome/doc/guides/icons.md
create mode 100644 ivette/src/dome/doc/guides/quickstart.md
create mode 100644 ivette/src/dome/doc/guides/styling.md
diff --git a/ivette/Makefile b/ivette/Makefile
index 2953dba00dc..97c58206a37 100644
--- a/ivette/Makefile
+++ b/ivette/Makefile
@@ -28,9 +28,21 @@ lint: dome-pkg dome-templ
# --- Ivette Documentation
# --------------------------------------------------------------------------
+GUIDES= src/dome/doc/guides
+VERSION=$(shell echo "console.log(require('./package.json').version)" | node -)
+
doc:
@echo "[Ivette] documentation"
@yarn run typedoc
+ @mkdir -p doc/html/guides
+ @find $(GUIDES) -name "*.md" -exec cp -f {} doc/html/guides/ \;
+ @find doc/html/guides -name "*.md" -print -exec pandoc \
+ --standalone --toc --toc-depth=2 --to html \
+ --metadata title="Ivette Documentation" \
+ --metadata version="v$(VERSION)" \
+ --template doc/pandoc/template.html \
+ --lua-filter doc/pandoc/href.lua \
+ {} -o {}.html \; -delete
# --------------------------------------------------------------------------
# --- Ivette Plugins
diff --git a/ivette/doc/pandoc/href.lua b/ivette/doc/pandoc/href.lua
new file mode 100644
index 00000000000..080635d1533
--- /dev/null
+++ b/ivette/doc/pandoc/href.lua
@@ -0,0 +1,4 @@
+function Link(el)
+ el.target = string.gsub(el.target, "%.md", ".md.html")
+ return el
+end
diff --git a/ivette/doc/pandoc/template.html b/ivette/doc/pandoc/template.html
new file mode 100644
index 00000000000..55ae1b2eb9c
--- /dev/null
+++ b/ivette/doc/pandoc/template.html
@@ -0,0 +1,87 @@
+<!DOCTYPE html>
+<html class="default no-js">
+<head>
+ <meta charset="utf-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+ <title>$subtitle$ | $title$ – $version$</title>
+ $if(description)$
+ <meta name="description" content="$description$">
+ $endif$
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <link rel="stylesheet" href="../assets/css/main.css">
+</head>
+<body>
+ <header>
+ <div class="tsd-page-toolbar">
+ <div class="container">
+ <div class="table-wrap">
+ <div class="table-cell" id="tsd-search"
+ data-index="../assets/js/search.json" data-base=".">
+ <div class="field">
+ <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
+ <input id="tsd-search-field" type="text" />
+ </div>
+ <ul class="results">
+ <li class="state loading">Preparing search index...</li>
+ <li class="state failure">The search index is not available</li>
+ </ul>
+ <a href="../index.html" class="title">$title$ - $version$</a>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="tsd-page-title">
+ <div class="container">
+ <ul class="tsd-breadcrumb">
+ <li><a href="README.md.html">Guides</a></li>
+ </ul>
+ <h1 id="MAIN">$subtitle$</h1>
+ </div>
+ </div>
+ </header>
+ <div class="container container-main">
+ <div class="row">
+ <div class="col-8 col-content">
+ <div class="tsd-panel tsd-typography">
+ $body$
+ </div>
+ </div>
+ <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
+ <nav class="tsd-navigation primary">
+ <a class="root" href="../index.html">$title$</a>
+ </nav>
+ <nav class="tsd-navigation secondary menu-sticky">
+ <a href="#MAIN"><b>$subtitle$</b></a>
+ <ul class="before-current">
+ $if(link)$
+ $if(toc)$
+ $for(link)$
+ $if(link.toc)$
+ $table-of-contents$
+ $else$
+ <li><a href="$link.href$.html">$link.title$</a></li>
+ $endif$
+ $endfor$
+ $else$
+ <ul>
+ $for(link)$
+ <li><a href="$link.href$.html">$link.title$</a></li>
+ $endfor$
+ $endif$
+ $else$
+ $table-of-contents$
+ $endif$
+ </ul>
+ </ul>
+ </nav>
+ </div>
+ </div>
+ </div>
+ <div class="overlay"></div>
+ <script src="../assets/js/main.js"></script>
+ <script>
+ if (location.protocol == 'file:')
+ document.write('<script src="../assets/js/search.js"><' + '/script>');
+ </script>
+</body>
+</html>
diff --git a/ivette/src/dome/doc/guides/application.md b/ivette/src/dome/doc/guides/application.md
new file mode 100644
index 00000000000..8abb0b0ebdc
--- /dev/null
+++ b/ivette/src/dome/doc/guides/application.md
@@ -0,0 +1,121 @@
+---
+subtitle: Application Design
+---
+
+This tutorial introduces how to design a **Dome** application within the
+**Electron** & **React** frameworks. You shall be reasonably familiar with
+**React** concepts, but no knowledge of **Electron** is required.
+
+A desktop **Dome** application looks like a native application, but is actually
+a static web page rendered in a **Chrome** web browser. This is what provides
+the **Electron** framework by default. **Dome** is simply a library of **React**
+components and development templates tuned together to enable professional
+application development.
+
+This tutorial provides an overview of this environment and how to design a typical
+**Dome** application.
+
+## System Architecture
+
+Following the **Electron** framework design, your application will consists of
+two different processes interacting with each others.
+One is responsible for the management of the main GUI resources
+(windows, menu-bar, desktop interaction, user settings, etc.)
+and is named the `Main` process.
+The second one will be responsible for running the
+web page holding the main application window, and is named the `Renderer` process.
+Both kind of process communicates through the message-passing API provided by
+the **Electron** framework.
+
+When several instances of your application are running simultaneously, each invokation
+have its own window, running its owan, separate `Renderer` process. However, the
+**Dome** framework automatically makes them sharing the same `Main` process.
+
+Hence, each application instance has its own working directory and command-line arguments,
+depending on how its has been launched by the user. The **Dome** framework build
+both command-line and desktop entry points, depending on each target platform.
+
+## Event Driven Design
+
+On the renderer process side, the **React** framework induces a natural design where
+_Application State_ is separated from _Application Rendering_. Moreover,
+following a popular design introduced with **Redux**, application rendering tend
+to be written like a pure function (or _view_) on the state, where user
+actions are just state updater callbacks. Each time the state is modified, the
+entire application rendering is recomputed, and **React** computes a minimal
+diff to apply on the web page displayed in the main application window.
+
+Putting everything together, its is recommended to design **Dome** application
+into two different parts, both running in the `Renderer` process of each
+application instance:
+
+- **Application Internals (State)**
+holding your application state and data and updating it in response to user or
+system events;
+
+- **Application Components (View)**
+responsible for rendering the application main window and
+binding callbacks to application services.
+
+<img src="dataflow.png" style="float: right; width: 30em"/>
+
+Such an architecture is typical of a _Model-View-Controller_ design, but
+revisited to scale. In particular, data flow between those three different
+layers shall follow a unique-direction pattern in order to avoid the
+combinatorial explosion of interactions between components that is generally
+observed in most Model-View-Controller designs.
+
+Hence, data-flow shall follow one of the following routes between these
+three layers, illustrated above:
+
+- from `State` to `View` : your rendering components shall only access the
+current application state and data;
+- from `View` to `State` or `System` : user action callbacks shall only trigger
+state update or system operation, not any other view direct modification.
+- from `System` to `State` : upon completion, system services shall trigger state
+updates that would in turn trigger new requests and view re-rendering.
+
+## Data Management
+
+To implement the recommended data-flow described above, you may use a full
+featured [Redux](https://redux.js.org) platform or any other framework of your
+choice. However, **Dome** provides you with many facilities for implementing
+your data flow.
+
+- **Global States** are necessary to implement the unidirectional data-flow. These
+ data are stored in the renderer process, but outside of the view hierarchy of
+ **React** components actually mounted in the DOM. Hence, it remains consistent whatever
+ the evolution of the view. See `Dome.State` class and the associated custom **React** hooks
+ to implement global states. You may also use global JavaScript variables and emit events
+ on your own.
+
+- **Local States** are necessary to maintain local states associated
+ to views. We strongly encourage the use of the `Dome.useState()` hook for this
+ purpose, since it generalizes `React.useState()` with persistent window settings
+ (see below).
+
+- **View Updates** to make your views listening for updates of the various data
+ sources, we encourage to use the **React** hooks we provide, since they
+ transparently make your components to re-render when required. However,
+ sometimes you will need to respond to special events by hand. For this purpose,
+ you can use **Dome** as a central event emitter, by using `Dome.emit()`,
+ `Dome.on()` and `Dome.off()` functions. Moreover, the `Dome.useUpdate()` and
+ `Dome.useEvent()` hooks can be used to make your components being notified by
+ events.
+
+- **Window Settings** are stored in the user's home directory but remain
+ generally unnoticed by most users, although they are responsible for a good user
+ experience. They typically include the window's position and dimension,
+ resizable items position, fold/unfold states, presentation options, etc. Most
+ **Dome** components with presentation options can be assigned a `settings` key
+ to make their state persistent. Contrary to Global Settings, however, they are
+ not shared across several windows. You may also access these data by using
+ `Dome.setWindowSetting()` and `Dome.getWindowSetting()`, or the **React** hook
+ `Dome.useWindowSetting()`.
+
+- **Global Settings** are stored in the user's home directory and automatically
+ saved and load with your application; they are typically modified _via_ the
+ Settings Window, which is accessible from the application menubar. In **Dome**,
+ you access these data by using `Dome.setGlobalSetting()` and
+ `Dome.getGlobalSetting()`, or the **React** hook `Dome.useGlobalSetting()`.
+ Settings must be JSON serializable JavaScript values.
diff --git a/ivette/src/dome/doc/guides/development.md b/ivette/src/dome/doc/guides/development.md
new file mode 100644
index 00000000000..a1bfa4c5460
--- /dev/null
+++ b/ivette/src/dome/doc/guides/development.md
@@ -0,0 +1,203 @@
+---
+subtitle: Application Development
+---
+
+The [Quick Start](quickstart.md) tutorial introduces how to setup a new application project,
+and [Application Design](application.md) draw a high-level view of how it works.
+This tutorial goes into more details about the development environment provided by the **Dome**
+framework.
+
+
+## HTML & JavaScript Environment
+
+The Web environment for designing your application is based on the following
+framework:
+
+- **Electron** [v5.0+](https://electronjs.org) runtime environment (packaging Chrome and Node)
+- **Node** [v12.0+](https://nodejs.org/dist/latest-v12.x/docs/api) provided by Electron
+- **Chromium** [v73.0+](https://www.chromium.org/Home) HTML rendering engine provided by Electron
+
+You will write your application in a an environment setup with the following
+JavaScript features:
+
+- **Webpack** for packaging the application from sources
+- **Babel** to parse language extensions
+- **Babel Presets Env** to use ECMA modules and JavaScript strict mode
+- **Babel Presets React** to use JSX react notation in all your `*.js` files
+- **Babel Object Rest Spread** to use object spread syntax `{ ...props }`
+- **React v16** with its latest features (including Hooks)
+- **React Hot Loader** for [live-editing](hotreload.md) your application
+- **CSS Loader** to load and install `*.css` files
+
+## Available Packages
+
+The implementation and internals of the **Dome** framework rely on
+high-quality and mature popular packages. They are automatically packed
+into your dependencies by the provided template makefile. We list them here
+since you may re-use them for your own purpose:
+
+- [**Lodash**](https://lodash.com) convenient JavaScript utilities
+- [**React-Virtualized**](http://bvaughn.github.io/react-virtualized)
+for layout of large data set in list, tables and grids
+- [**React-Draggable**](https://github.com/mzabriskie/react-draggable)
+for straightforward drag-and-drop features
+- [**CodeMirror**](https://codemirror.net) for rich text capabilities and edition
+that scales on large document
+
+## Project Files Organization
+
+The main directory holding your application project with **Dome** consists of
+several files and directories. Each is created and/or managed by various
+entities : yourself the **Developer**, the **Dome** template makefile, the
+**Yarn** JavaScript package manager and the **Electron** suite of
+utilities. Parts of those files are generated and updated on demand and shall or
+shall _not_ be tracked in your source version control system, be it based on `git`,
+`svn` or anything else.
+
+Most files are actually created and used by **Dome**, **Electron** and **Yarn**.
+However, that are _in fine_ under the responsibility of the **Developer**
+since you can edit and extend them to fit your needs.
+Those generated files generally contains comments to indicate how you
+can extend them. You shall put those files under version control only if you edit them.
+
+As depicted in the [Quick Start](quickstart.md) tutorial, the only file you
+need to create by yourself is the main `Makefile`, with a minimal content
+limited to:
+
+```makefile
+DOME="..." ;; path to your dome installation
+include $(DOME)/template/makefile
+```
+
+The following table lists the main files and directories of your project, with
+the associated entity responsible for it, and whether they should be tracked by
+your source version control system (VCS).
+
+Optional files are tagged with « (Opt.) » in the corresponding `Entity` column,
+and are _not_ generated by default. Similarly, files mainly used by the system
+but that can still be configured by the developer are tagged with « (+Dev) ».
+Files are tagged with « ✓(*) » in the `VCS` column shall be tracked only if you
+actually modified them.
+
+| File or Directory | Description | Entity | VCS |
+|:------------------|:------------|:-------:|:---:|
+| `./Makefile` | Drives the build system | **Developer** | ✓ |
+| `./src/main/` | Sources for the main process | **Developer** | ✓ |
+| `./src/main/index.js` | Main process entry point | **Electron** (+Dev) | ✓ |
+| `./src/renderer/` | Sources for the renderer process | **Developer** | ✓ |
+| `./src/renderer/index.js` | Renderer process entry point | **Electron** (+Dev) | ✓ |
+| `./src/renderer/Application.js` | Top React component of the main application window | **Developer** | ✓ |
+| `./src/renderer/Preferences.js` | Top React component of the user preferences window | **Developer** | ✓ |
+| `./src/common/` | Sources for _both_ processes | **Developer** (Opt.) | ✓ |
+| `./static/` | Static resources | **Developer** (Opt.) | ✓ |
+| `./package.json` | JavaScript packages configuration | **Yarn** (+Dev) | ✓ |
+| `./node_modules` | Downloaded packages | **Yarn** | ð„‚ |
+| `./yarn.lock` | Packages versions stamps | **Yarn** | ✓ |
+| `./electron-webpack.json` | Electron configuration | **Electron** (+Dev) | ✓(*) |
+| `./babelrc` | Babel configuration | **Electron** (+Dev) | ✓(*) |
+| `./webpack.main.json` | Webpack main process config. | **Electron** (+Dev) | ✓(*) |
+| `./webpack.renderer.json` | Webpack renderer process config. | **Electron** (+Dev) | ✓(*) |
+| `./.dome-*` | Dome makefile stamps | **Dome** | ð„‚ |
+| `$(DOME)/*` | Dome framework clone | **Dome** | (var.) |
+| `./dist/` | Packaged application | **Dome** | ð„‚ |
+| `./bin/` | Local command-lines | **Dome** | ð„‚ |
+
+The main entry points of the two **Electron** processes running your application,
+`src/main/index.js` and `src/renderer/index.js` shall be modified with extreme care,
+since they are in charge with the correct bootstrap of your application.
+The generated files from **Dome** templates contains explicit comments and guidelines.
+
+You may want to modify the name of your application top-level **React** components,
+namely `src/renderer/Application.js` and `src/render/Preferences.js` by default.
+To do this, you shall hook into the
+`src/renderer/index.js` file and follow the provided comments and guidelines,
+and set the `DOME_CUSTOM_ENTRIES` variable into your own `./Makefile` to make
+**Dome** aware about this.
+
+If you need static resource files to be packed with your application, put them in the `static` directory.
+You can then access to their actual path from your code by using the `System.getStatic(<path>)` utility function.
+
+The location of the **Dome** resources actually depends on the developer
+profile, as explained in more detailed in the [Live Editing](hotreload.md) tutorial.
+To summarize:
+- for normal developers, it can be a local copy of the dome framework, for instance in your `/usr/local/lib/dome` directory;
+- for developers working with a specific or modified version of the dome framework, it can be in the local
+`./dome/` directory of your project, with or without versioning control;
+- for **Dome** developers, it is also possible to clone the Git repository inside the `./src/dome/` sub-directory of your
+project, hence also enabling live-editing of **Dome** itself;
+- for **Dome** maintainers, it is even possible to use the root of the **Dome** development repository as an application project
+in itself, for demos, examples or testing purposes.
+
+Most of the **Electron** configuration files depends on the definition of the
+`DOME` environment variable to find the necessary resources for your application
+during development. Commands initiated by **Dome** from `$(DOME)/template/makefile`
+will explicitly copy the `$(DOME)` makefile variable into the `$DOME` shell environment
+variable when calling the **Electron** builder utilities, and might use it to generate static
+files from templates, if necessary.
+
+If you ever _move_ the place where **Dome** is installed, you
+probably have to inspect the generated files that you have modified to check
+if they still behave as expected.
+
+Notice, however, that distributed versions of
+the application (those accessible from the `./dist/` directory) are
+self-contained: they are _not_ tied to your local installation of **Dome**.
+
+The command-line version of the application is accessible to the developer from the `./bin` directory.
+
+# Common Development Tasks
+
+Most development tasks shall be accessible from your `./Makefile`, and simply delegate to the
+predefined **Dome** targets in `$(DOME)/template/makefile` ; however, for very specific needs,
+you can borrow the content of the template makefile into your own one and modify it at your
+convenience. The **Dome** environment will not target this template makefile explicitly.
+
+The top target of the **Dome** template makefile is `make dome-help`,
+which is thus activated by default unless you put your own targets _before_
+its inclusion. The `dome-help` target simply echoes a short list of all the
+`dome-xxx` predefined targets in the template. It also reports on
+actual values of makefile variables used by the template.
+
+```
+$ make dome-help
+
+[Dome] Builtin Targets:
+ make dome-help This help
+ make dome-dev Run application in development mode
+ make dome-app Compile application
+ make dome-dist Package application for production
+ make dome-doc Generate Dome documentation
+ make dome-api Generate Application documentation
+ make dome-pkg Install development packages
+ make dome-templ Update templates
+ make dome-reboot Rebuild templates from scratch
+ make dome-clean Remove dome temporary files
+ make dome-plugins Package plugins for distribution
+
+[Dome] Development:
+ Dome framework DOME = '…'
+ Local command DOME_CLI = '…'
+ Arguments (dev) DOME_ARGS = '…'
+ Export modules DOME_EXPORTS = '…'
+ Plugin modules DOME_PLUGINS = '…'
+
+[Dome] Documentation:
+ Application APP = '…'
+ Copyright COPYRIGHT = '…'
+ Dome framework DOME_DOC = '…'
+ Output dir DOME_DOC = '…'
+ Public API DOME_API = '…'
+
+```
+
+As depicted above, the **Dome** template also provides two extensible targets `help::` and `clean::`.
+By default, the `make clean` would only remove the **Dome** stamp files, not the actually generated files,
+since they can have been modified when developing the application. This can cause, however, an _update_ of
+configuration files that can be managed incrementally, typically for the `package.json` and the installed
+JavaScript packages.
+
+The **Dome** framework can generate its own documentation locally, hence you may consult it offline. It
+is also capable of generating internal **JSDoc** documentation of the application itself. The application
+documentation does _not_ contain the framework documentation, though.
+
+The environment variable can be redefined _via_ your own Makefile before the **Dome** template inclusion.
diff --git a/ivette/src/dome/doc/guides/dome.md b/ivette/src/dome/doc/guides/dome.md
new file mode 100644
index 00000000000..15df888a882
--- /dev/null
+++ b/ivette/src/dome/doc/guides/dome.md
@@ -0,0 +1,28 @@
+---
+subtitle: Dome Framework
+---
+
+**Dome** allows you to build native, desktop applications using
+[React](https://reactjs.org) javascript technology. It is build upon the
+[Electron](http://electron.atom.io) framework, featuring a full-featured Chromium
+engine which renders the graphical user interface to the user.
+
+The **Dome** framework provides you with the following facilities:
+- all-in-one pre-configured rich development environment
+- live-editing of your application code
+- a collection of ready-to-use, well designed, scalable components
+- easy integration with any other React components from your own
+- binary distribution for all supported platform (Windows, Linux and MacOS)
+
+## To Start With
+
+- [Quick Start](quickstart.md)
+- [Live Editing](hotreload.md)
+- [Application Design](application.md)
+- [Application Development](development.md)
+
+## References
+
+- [Custom Hooks](hooks.md)
+- [Icon Gallery](icons.md)
+- [Glossary](glossary.md)
diff --git a/ivette/src/dome/doc/guides/glossary.md b/ivette/src/dome/doc/guides/glossary.md
new file mode 100644
index 00000000000..d0a89315011
--- /dev/null
+++ b/ivette/src/dome/doc/guides/glossary.md
@@ -0,0 +1,32 @@
+---
+subtitle: Glossary
+---
+
+## Basic Concepts
+
+- **Component** a React Component definition (class of function)
+- **Element** a React Component instance of a Component, typically `<Component ...>`
+- **Elements** a fragment of any number of elements, typically the `children` properties of elements
+- **Render Prop** a function returning element(s), typically used instead of children elements
+
+## Component Properties
+
+- `id` an element identifier
+- `icon` an icon identifier, as listed in the [icon gallery](tutorial-icons.html)
+- `label` a short text used as the displayed title of a component
+- `text` textual content to be printed on screen
+- `title` a description for a component, usually provided in a tooltip box
+- `settings` a key for making local state(s) persistent in user's settings
+- `value` the value associated to some basic control (see `onChange`)
+- `state` an object holding some current state (see `onUpdate`)
+- `default` identifies the element selected by default in a list
+- `selected` whether an element is selected or not (never by default)
+- `disabled` whether an element will not responds to user actions (never by default)
+- `selection` the identifier or value of current selection, or `undefined` (see `onSelect`)
+- `children` the children elements of a component instance
+- `onClick` a callback function in response to a click event
+- `onClose` a callback function in response to closing action
+- `onChange` a callback function in response to value changes (see `value`)
+- `onUpdate` a callback function in response to (partial) state updates (see `state`)
+- `onSelection` a callback function in response to user selection (see `selection`)
+- `style` an inlined CSS style object to inject in a DOM element
diff --git a/ivette/src/dome/doc/guides/hooks.md b/ivette/src/dome/doc/guides/hooks.md
new file mode 100644
index 00000000000..100724e3cab
--- /dev/null
+++ b/ivette/src/dome/doc/guides/hooks.md
@@ -0,0 +1,22 @@
+---
+subtitle: Custom React Hooks
+---
+
+The **Dome** framework provides several [React Hooks](https://reactjs.org/docs/hooks-intro.html)
+to ease your developpement process. Here is a summary of them.
+
+- [`useUpdate(evt)`](dome_.html#.useUpdate) to trigger re-rendering on **Dome** events;
+- [`useEvent(emitter,event,callback)`](dome_.html#.useEvent) to trigger callbacks on events;
+- [`useForceUpdate()`](dome_.html#.useForceUpdate) to trigger re-rendering on demand;
+- [`useState(settings,defaultValue)`](dome_.html#.useState)
+ similar to `React.useState()` with optional persistent _window_ settings;
+- [`useSwitch(settings,defaultValue)`](dome_.html#.useSwitch)
+ similar to `React.useState()` for boolean values with _window_ settings;
+- [`useGlobalSetting(settings,defaultValue)`](dome_.html#.useGlobalSetting)
+ similar to `React.useState()` with optional persistent _global_ settings;
+- [`useHistory(settings,defaultValue)`](dome_.html#.useHistory)
+ for managing histories
+- [`useClock(period,initStart)`](dome_.html#.useClock)
+returns start/stop clocks synchronized on period.
+- [`useCommand()`](dome_.html#.useCommand) for working with different application instances.
+- See also the [`Dome.State`](dome(renderer).State.html) and the associated hooks.
diff --git a/ivette/src/dome/doc/guides/hotreload.md b/ivette/src/dome/doc/guides/hotreload.md
new file mode 100644
index 00000000000..24279c93ad0
--- /dev/null
+++ b/ivette/src/dome/doc/guides/hotreload.md
@@ -0,0 +1,47 @@
+---
+subtitle: Live Code Editing
+---
+
+The **Dome** framework comes with live-editing facilities, provided by a
+combination of
+[Webpack Hot Module Reloading](https://webpack.js.org/concepts/hot-module-replacement)
+and [React Hot Loader](http://gaearon.github.io/react-hot-loader).
+This allows you to live edit your code and style sheets in real time while application
+is running. This feature is only enabled in development mode, not in production mode
+used when packaging the application for some platform.
+
+Hot reloading for **React** components is known to be a fragile feature and to
+suffer from certain limitations. Typically, files that can trigger live updates
+must be reachable from the `./src` directory, without traversing symbolic links.
+Style sheets in `*.css` files can be live edited, and **React** components in
+`*.js` files as well. Most **React** components can be live-edited, provided
+they are defined in top-level variables or exported by modules. Generally, the
+component states are preserved during live-editing.
+
+For live-editing to work properly, your source code must follow strict
+configuration settings. These rules are enforced when using configuration files
+and application entry points generated from **Dome** templates. Pay attention to
+the provided comments in generated files when modifying them.
+
+By default, we suggest to install the **Dome** framework in the sub-directory `./dome`
+of your project. Being outside `./src`, this normally prevents **Dome** files to
+be live-edited. If you want to also live-edit the framework, you shall move the
+`$(DOME)` directory inside your own `./src`.
+In particular, you might install the framework with `DOME=src/dome` for instance.
+
+**State Management:** hot-reloading on **React** components preserves application
+states _only_ when they are stored outside the reloaded module. This is the case
+for local states maintained in **React** components, as they live in the virtual DOM.
+However, for global application state stored in global variables of modules,
+they simply vanish when a module is hot-reloaded. Worst, the virtual DOM will
+be still bound to the _old_ versions of the modules. However, you usually don't
+want to live-edit the global state of your application and mix new data with
+old ones. A good practice is to separate files holding global state from files
+implementing views. Hence, live-editing the views will not cause the global state
+modules to reload, and views will stay in sync with your data. If you ever modify
+the global state, you will have to reload the application window (`CmdOrCtrl-R`).
+
+**Versioning Note:** the framework currently sticks on `webpack` version 3 and
+`react-hot-loader` version 3, because of limitations and issues when using
+`electron-webpack` with most recent versions of those libraries. However, we
+hope to be able to migrate to newer versions as soon as possible.
diff --git a/ivette/src/dome/doc/guides/icons.md b/ivette/src/dome/doc/guides/icons.md
new file mode 100644
index 00000000000..ee71eb82740
--- /dev/null
+++ b/ivette/src/dome/doc/guides/icons.md
@@ -0,0 +1,3 @@
+<!-- Icon Gallery -->
+
+<!-- (Generated) -->
diff --git a/ivette/src/dome/doc/guides/quickstart.md b/ivette/src/dome/doc/guides/quickstart.md
new file mode 100644
index 00000000000..142497c0ec5
--- /dev/null
+++ b/ivette/src/dome/doc/guides/quickstart.md
@@ -0,0 +1,26 @@
+---
+subtitle: Quick Start
+---
+
+We strongly recommand to use [**Yarn**](https://reactjs.org)
+for installing the necessary Node packages and their dependencies.
+
+Then, prepare a directory for developing your application, and download
+the Dome Application Framework into sub-directory `dome`.
+You shall now setup a makefile for your application as follows:
+
+<pre>
+ # Makefile
+ include dome/template/makefile
+ all: dome-dev
+</pre>
+
+Now, simply type `make` and all the necessary packages will be automatically
+installed and configured. This can take a while for the very first installation.
+You will be prompted for generating a default `package.json` file
+if you do not have some already.
+
+Eventually, your application will start with
+a « _Hello World_ » window.
+Now, you can _live edit_ the generated `src/renderer/Application.js` which is the main entry point
+of your application and see what happens into the main window.
diff --git a/ivette/src/dome/doc/guides/styling.md b/ivette/src/dome/doc/guides/styling.md
new file mode 100644
index 00000000000..0488e131916
--- /dev/null
+++ b/ivette/src/dome/doc/guides/styling.md
@@ -0,0 +1,65 @@
+---
+subtitle: Styling Components
+---
+
+This tutorial explains how **Dome** style sheets are organized and how
+to reuse them for styling your own components. Although modern styling
+usually rely on _style preprocessors_ to leverage the complexity of
+CSS style sheets development, the approach used here is based on separation
+of concerns and multi-class styling. The advantage is that you can
+develop your _own_ style sheets, while still being able
+to re-use the existing classes provided by the framework.
+
+All CSS classes provided by **Dome** start with prefix `dome-` ; you shall not
+use such a prefix when designing your own classes. Many class names are provided
+with optional or mandatory variants. Typically:
+
+- `dome-<base>[-<a>,<b>,...]` describes class `dome-<base>` and its variants
+`dome-<base>-<a>`, `dome-<base>-<b>` _etc_.
+
+- `dome-<name>-[<a>,<b>,...]` describes classes `dome-<name>-<a>`, `dome-<name>-<b>` _etc_.
+
+## Platform Context
+
+These classes can be used when writing selectors in order to style things
+with respect to the target platform. The main window container is attributed
+with one of the following class:
+
+- `dome-platform-[darwin,linux,windows]` derived from the `process.darwin`
+global variable (**Node.js** environment).
+
+- `dome-window-[active|inactive]` depending on whether the main application window
+has focus or not.
+
+## Color Palettes
+
+Attributing colors to graphical elements is often an issue, since a precise
+hex variants shall be tuned depending on the surrounding context. However,
+base colors are provided in public classes for several usages:
+
+- `dome-color-frame` background, foreground and borders for
+window frames, which includes tool-bars, status-bars, tabs and such.
+Those colors actually depend on the focus state of the main application window.
+
+- `dome-color-[dragzone|dragging]` for painting the background of a dragging
+zone, typically a splitting rule. The `dragzone` variant is completely
+transparent with a very transparent light gray when hovered.
+The `dragging` variant is semi-transparent blended blue with light gray.
+All these drag background effects are smoothly transitioned.
+
+## Text Properties
+
+- `dome-text-[label|title|descr]` for labels (_eg._ buttons, tabs, menu
+entries), titles (larger labels) and descriptions (_eg._ tooltips).
+Uses a sans-serif font, is non-selectable and truncated with an ellipsis.
+
+- `dome-text-[data|code]` for selectable text, typically input fields.
+Uses a sans-serif font (for `data`) or monospace font (for `code`),
+never wraps and is clipped when overflow.
+
+## Component Layout
+
+The entire application uses the `box-model` box-sizing property by default,
+since it is usually much more consistent with nested `<div>` components.
+Similarly, default margins and paddings are set to `0px` to avoid unwanted
+messy background issues.
--
GitLab