Add instructions to build Taipy's and Taipy's GUI JavaScript bundles. (#650)

Co-authored-by: Fabien Lelaquais <fabien@lelaquais.fr>

INSTALLATION.md

@@ -0,0 +1,135 @@
+# Installation
+
+There are different ways to install Taipy, depending on how you plan to use it.
+
+If your goal is to look into the code, modify and improve it, go straight
+to the [source installation](#installing-for-development) section.
+
+Taipy needs your system to have Python 3.8 or above installed.
+
+## Installing from PyPI
+
+The easiest way to install Taipy is from the
+[Pypi software repository](https://pypi.org/project/taipy/).
+
+Run the command:
+```console
+$ pip install taipy
+```
+
+If you are running in a virtual environment, you will have to issue the command:
+```console
+$ pipenv install taipy
+```
+
+These commands install the `taipy` package in the Python environment with all its
+dependencies.
+
+## Installing from GitHub
+
+The development version of Taipy is updated daily with changes from the Taipy R&D and external
+contributors whom we praise for their input.
+
+The development version of Taipy can be installed using *pip* and *git*:
+
+```console
+$ pip install git+https://git@github.com/Avaiga/taipy
+```
+
+## Installing for development
+
+If you need the source code for Taipy on your system so you can see how things are done or maybe
+participate in the improvement of the packages, you can clone the GitHub repository:
+
+```console
+$ git clone https://github.com/Avaiga/taipy.git
+```
+
+This creates the 'taipy' directory holding all the package's source code.
+
+### Building the JavaScript bundles
+
+Taipy (and Taipy GUI that it embeds) has some code dealing with the client side of the web
+applications.<br/>
+This code is written in [TypeScript](https://www.typescriptlang.org/), relies on
+[React](https://reactjs.org/) components, and is packaged into JavaScript bundles that are sent to
+browsers when they connect to all Taipy applications that have a graphical interface.
+
+There are two main JavaScript bundles that can be built:
+- Taipy GUI: All the graphical interfaces that Taipy GUI can generate are based on a set of
+  generated files, including the web application and all the predefined visual elements.
+- Taipy: A set of visual elements dedicated to Scenario Management.
+
+**Prerequisites**: If you need to build the JavaScript bundle, you need to make sure that the
+[Node.js](https://nodejs.org/) JavaScript runtime version 18 or above is installed on your
+machine.<br/>
+Note that Node.js comes with the [`npm` package manager](https://www.npmjs.com/) as part
+of the standard installation.
+
+The build process is described in the [Taipy GUI front-end](frontend/taipy-gui/README.md) and
+ [Taipy front-end](frontend/taipy/README.md) README files.<br/>
+ The Taipy GUI bundle must be built first, as the Taipy front-end code depends on it.
+
+Here is the sequence of commands that can be issued to build both sets of files:
+
+```console
+# Current directory is the repository's root directory
+#
+# Build the Taipy GUI bundle
+$ cd frontend/taipy-gui
+$ cd dom
+$ npm i
+$ cd ..
+$ npm i --omit=optional
+$ npm run build
+#
+# Build the Taipy front-end bundle
+$ cd ../taipy # Current directory is [taipy-dir]/frontend/taipy
+$ npm i
+$ npm run build
+```
+
+These commands should create the directories `taipy/gui/webapp` and `taipy/gui_core/lib` in the
+root directory of the taipy repository.
+
+### Debugging the JavaScript bundles
+
+If you plan to modify the front-end code and need to debug the TypeScript
+code, you must use the following:
+```
+$ npm run build:dev
+```
+
+instead of the *standard* build option.
+
+This will preserve the debugging symbols, and you will be able to navigate in the
+TypeScript code from your debugger.
+
+> **Note:** Web application location
+>
+> When you are developing front-end code for the Taipy GUI package, it may
+> be cumbersome to have to install the package over and over when you know
+> that all that has changed is the JavaScript bundle that makes the Taipy
+> web app.
+>
+> By default, the Taipy GUI application searches for the front-end code
+> in the `[taipy-gui-package-dir]/taipy/gui/webapp` directory.<br/>
+> You can, however, set the environment variable `TAIPY_GUI_WEBAPP_PATH`
+> to the location of your choice, and Taipy GUI will look for the web
+> app in that directory.<br/>
+> If you set this variable to the location where you build the web app
+> repeatedly, you will no longer have to reinstall Taipy GUI before you
+> try your code again.
+
+
+## Running the tests
+
+To run the tests on the package, you need to create a virtual
+environment and install the development packages:
+
+Here are the commands to issue:
+
+```console
+pipenv install --dev
+pipenv run pytest
+```

frontend/README.md

@@ -0,0 +1,14 @@
+# Front-end source code
+
+This directory contains the source code for the front-end parts of Taipy GUI and Taipy.
+
+- `./taipy-gui`: The source files for building the front-end part of Taipy GUI.<br/>
+  This includes the web application used by Taipy GUI to expose user interfaces as
+  well as all the visual elements, implemented in React.
+- `./taipy`: The source files for building the front-end part of Taipy.<br/>
+  This includes all the Taipy elements for Scenario Management.
+
+Note that before the `taipy` part is built, the `taipy-gui` part must have been built.
+
+Please check the [Taipy GUI Front-end](taipy-gui/README.md) and [Taipy Front-end](taipyREADME.md)
+README files for details.

frontend/taipy-gui/README.md

@@ -0,0 +1,34 @@
+# Taipy GUI front-end
+
+This directory contains the source code of the Taipy GUI front-end bundle that includes the
+web app and all the elements natively available in Taipy GUI.
+
+## Prerequisites
+
+[Node.js](https://nodejs.org/) JavaScript runtime version 18 or above must be installed on your
+machine.<br/>
+Note that Node.js comes with the [`npm` package manager](https://www.npmjs.com/) as part
+of the standard installation.
+
+## Build
+
+To build the Taipy GUI bundle, you must set your current directory to this directory and then
+run the following commands:
+
+```console
+# Current directory is the directory where this README file is located:
+#   [taipy-dir]/frontend/taipy-gui
+#
+# Install the DOM dependencies (once and for all)
+$ cd dom
+$ npm i
+$ cd ..
+# Install the web app dependencies
+$ npm i --omit=optional
+# Build the web app and all elements
+$ npm run build
+```
+
+
+After these commands are successfully executed, a new directory will be created in
+`[taipy-dir]/taipy/gui/webapp` containing all the code that the Taipy GUI front-end relies on.

frontend/taipy/README.md

@@ -0,0 +1,27 @@
+# Taipy front-end
+
+This directory contains the source code of the Taipy front-end bundle that includes the
+Scenario Management elements.
+
+## Prerequisites
+
+The Taipy GUI front-end web application must have been built.<br/>
+Check [this file](../taipy-gui/README.md) for more information.
+
+## Build
+
+To build the Taipy bundle, you must set your current directory to this directory and then
+run the following commands:
+
+```console
+# Current directory is the directory where this README file is located:
+#   [taipy-dir]/frontend/taipy
+#
+$ npm i
+# Build the Taipy front-end bundle
+$ npm run build
+```
+
+After these commands are successfully executed, a new directory will be created in
+`[taipy-dir]/taipy/gui_core/lib` containing all the code that implements the Taipy visual elements
+for Scenario Management.