Add how to develop frontend documentation. #234

jetfuel · 2018-01-31T19:59:51Z

No description provided.

varunarora

Don't be mad at me, I'm still your favorite boba friend

varunarora · 2018-01-31T22:31:58Z

docs/how_to_dev_frontend_en.md

@@ -0,0 +1,105 @@
+# VisualDL Web App Develop
+
+VisualDL has two major components. One is the Python/C++ SDK that logs the matrix during training,


Are you sure the SDK logs the matrices? If I am not wrong, they record vectors or scalars only

@varunarora matrices is my fancy word for data. I can change if it's inappropriate.

Haha unfortunately, matrices is a very loaded word. When one says "matrices", they are usually implying multidimensional data. Unfortunately, VDL doesn't do anything with multidimensional data today.

varunarora · 2018-01-31T22:36:10Z

docs/how_to_dev_frontend_en.md

+# VisualDL Web App Develop
+
+VisualDL has two major components. One is the Python/C++ SDK that logs the matrix during training,
+the other is the web-app that display visualized training data.


Technically, 3 components. Because the webapp is made up of two parts, the server side that serves like an API server to push content and a true "frontend" in JS

You mean the backend server that supplies the data, right?
I kinda combine them in my mind.

Nope, the server side (Flask) does. Frontend = server side + client side. And in our case, the SDK would be considered the "backend", but this is not the best use of the word backend, so we should just continue to use SDK for it.

varunarora · 2018-01-31T22:39:07Z

docs/how_to_dev_frontend_en.md

+VisualDL has two major components. One is the Python/C++ SDK that logs the matrix during training,
+the other is the web-app that display visualized training data.
+
+The web-app reads the extract data and draw scalars graph or histograms graphs.


I don't follow reads the extract data and draw.... I think once you have split the server side from the client side, you will be able to split the function as reads the logs from disk and visualizes... to a web pages

Also, I think web-app is just webapp

Yup, I combine the frontend and the backend server into one.

^my typo. its web app. I had thrown in an XML tag |space|, but the markdown parser stripped it out

Yeah i think the logical separation is: the server + frontend together being the frontend, and the rest being the sdk.

varunarora · 2018-01-31T22:39:56Z

docs/how_to_dev_frontend_en.md

+the other is the web-app that display visualized training data.
+
+The web-app reads the extract data and draw scalars graph or histograms graphs.
+The web-app is where VisualDL transforms the code data into graphs so users can visualize the training progress and make a better network design evaluation.


code data?

network design evaluation? is that a thing?

I will remove code

Don't we use VisualDL to evaluate the Neural Network?

So here the word "graph" is the tricky one. For many people, the first thing that might come to their mind is the computation graph and not the 2-D graph, as you intend to use it. That is why, to remove ambiguity, they use "scalar" plotting / graphing. You also would need to use that.

And I think "network architecture" is a more unambiguous term than "network design" - even though in all fairness you are right and I get what you are trying to say.

varunarora · 2018-01-31T22:42:18Z

docs/how_to_dev_frontend_en.md

+## Web App Overview
+The VisualDL web-app home page is constructed by three major Javascript files
+1. manifest.js: The manifest configures basic settings  
+1. vendor.js: The vendor.js stores all the 3rd party libraries.


Where are the manifest and vendor files? I can't even find them

They are under frontend/dist

Na, these are only the built files I think. Unless you are explaining the built stuff - which should come much much later - you probably don't want to talk about these. I don't actually see them in the source repo tree too, because built assets are usually not committed. Tell me if you see something that I don't!

varunarora · 2018-01-31T22:51:10Z

docs/how_to_dev_frontend_en.md

+
+1. Create Development Server
+
+    Once the setup up is complete. You may create a local development server to test new features or bug fixes.


Wait a second, you haven't described what the setup is. Most importantly, it is npm install which isn't mentioned anywhere

There is a link to download the npm earlier. I will state that they should follow the installation process as well.

Na, I think I wasn't clear. npm install installs npm packages locally, not installing npm.

ah sorry, the set up process here is for how to download the VisualDL code base. and the set up for pre-commit, etc.

varunarora · 2018-01-31T22:52:09Z

docs/how_to_dev_frontend_en.md

+## Development Flow
+The VisualDL is an open source project. Everyone is welcome to contribute to the project. To get start the process, please refer to [Contribute Code](contribute_code_en.md) to set up the environment.
+
+1. Create Development Server


More than creating a development server, you are definitely Running the development server.

Since it is not common to run a dev server for front-end separately from the server-side, you might have to also explicitly explain that as a part of the architecture.

Ah, I see. I will explicitly explain that we are only running the frontend development server.

varunarora · 2018-01-31T22:52:53Z

docs/how_to_dev_frontend_en.md

+    ```
+
+    This means a development server is ready and is accessible at `http://localhost:8999`. Open a browser and navigate to `http://localhost:8999` to access the VisualDL in development mode.
+    The development server will listen to any change made to the San or Javascript and update the changes in real time. We recommend doing web-app development under this mode to save time and resources.


San is JavaScript, so either one should be used here.

varunarora · 2018-01-31T22:53:14Z

docs/how_to_dev_frontend_en.md

+    This means a development server is ready and is accessible at `http://localhost:8999`. Open a browser and navigate to `http://localhost:8999` to access the VisualDL in development mode.
+    The development server will listen to any change made to the San or Javascript and update the changes in real time. We recommend doing web-app development under this mode to save time and resources.
+
+1. Prepare for Production


Perhaps these titles could be markdown h3 or h4'ed?

I don't think these are (1) and (2) steps. Build for production happens much later. Should probably happen in a production guide. What would be much nicer for this tutorial to focus on is how to run "the frontend", which is, the client side and server side.

Agree, I will change the format.

varunarora · 2018-01-31T22:55:25Z

docs/how_to_dev_frontend_en.md

+    If there is no error, You may now check-in the modified files.
+
+    **Note:** There is no need to check-in the generated files.
+    During the production process, the Travis-CI will generate new packaged files and overwrite the previously generated files. Avoid checking in the generated files can keep the repo commit history clean.


Travis-CI is an assumption; you don't know what CI tool other people are using. I would generally avoid reference to bundling and deployment processes, people have their own preferences.

I will remove the Travis-CI detail.

cs2be · 2018-02-01T18:21:21Z

docs/how_to_dev_frontend_en.md

+VisualDL has two three components.
+1. The Python/C++ SDK that logs the data during training.
+1. The single page client side app that visualized training data.
+1. The server(powered on Flask) that parses the saved data and delivers to the client side app for display.


maybe say "parses the logs data", to be consistent with the first point. Also, why are all the numbers "1."?

The server (powered on Flask) that reads the logs data and delivers it to the client side app for displaying graphs (scalars/histograms) and embeddings.

cs2be · 2018-02-01T18:24:39Z

docs/how_to_dev_frontend_en.md

+1. The single page client side app that visualized training data.
+1. The server(powered on Flask) that parses the saved data and delivers to the client side app for display.
+
+The server provided the needed data and pass to the client side to draw scalars or histograms. The users can visualize the training progress and make a better network architecture evaluation.


This point "The server provided the needed data and pass to the client side to draw scalars or histograms." is kind of repeat of the previous statement. Can probably remove.

cs2be · 2018-02-01T18:26:37Z

docs/how_to_dev_frontend_en.md

+
+The server provided the needed data and pass to the client side to draw scalars or histograms. The users can visualize the training progress and make a better network architecture evaluation.
+
+This article will go over the basic web-app architecture and development steps.


"and development guide."

cs2be · 2018-02-01T18:27:39Z

docs/how_to_dev_frontend_en.md

+npm reads `package.json` to build different package according to the packaging script.
+If you are not familiar with npm, please refer to the [npm documentation](https://docs.npmjs.com/) for more detail.
+
+Here is a list of the dependencies used in the VisualDL.


This might be too detailed for a quick start development guide, and also the requirements/versions may change. I think we should remove this section.

cs2be · 2018-02-01T18:28:04Z

docs/how_to_dev_frontend_en.md

+```
+
+## Development Flow
+The VisualDL is an open source project.


Add a new line before this one

cs2be · 2018-02-01T18:28:55Z

docs/how_to_dev_frontend_en.md

+Everyone is welcome to contribute to the project.
+To get start the process, please refer to [Contribute Code](contribute_code_en.md) to set up the environment.
+
+####Run The Client Side App In Development


Lets remove this step and add the new steps:

Prerequisite: Python 2.7, pip, npm, cmake

git clone [email protected]:PaddlePaddle/VisualDL.git
cd VisualDL
pip install -r requirements.txt
./scripts/setup_dev_env.sh
./scripts/start_dev_server.sh --logdir=<LOG_DIR>

cs2be · 2018-02-01T18:30:33Z

docs/how_to_dev_frontend_en.md

+
+```bash
+# Package all the needed info and update the manifest.js, vendor.js and index.js
+npm run release


The user shouldn't have to do this. The packaging should just be "python setup.py bdist_wheel". Even if the user runs npm run release, they don't know what to do with the release package.

cs2be · 2018-02-01T21:29:56Z

docs/how_to_dev_frontend_en.md

+
+San is a JavaScript component framework that helps the developer to implement web component in MVVM architecture pattern.
+
+San allows you to define a self-content view model in a .san file and attach view model objects to DOM objects.


cs2be · 2018-02-01T21:33:51Z

docs/how_to_dev_frontend_en.md

+
+## ECharts
+
+To draw the graphs we use ECharts's framework. It can pilot charts and graphs with just a few lines of code.


We use eCharts javascript library to render our charts and graphs. eCharts is a leading opensource charting library that supports numerous data visualization.

+To learn more about ECharts framework, please visit ECharts.

Add how to develop frontend documentation.

d07388e

jetfuel self-assigned this Jan 31, 2018

jetfuel requested review from cs2be and varunarora January 31, 2018 19:59

Provide a bit of information on san file.

d959451

varunarora reviewed Jan 31, 2018

View reviewed changes

jetfuel added 2 commits January 31, 2018 14:56

fix some information error

bd37fd5

Update the documention.

eeb6bc3

cs2be reviewed Feb 1, 2018

View reviewed changes

Simplify the documentation.

21196c8

cs2be previously approved these changes Feb 1, 2018

View reviewed changes

Remove unnecessary sentences

a362a6f

jetfuel dismissed cs2be’s stale review via a362a6f February 1, 2018 21:36

jetfuel force-pushed the addDevFrontEndDoc branch from 67f255f to a362a6f Compare February 1, 2018 21:36

Merge branch 'develop' into addDevFrontEndDoc

0e07e30

cs2be approved these changes Feb 1, 2018

View reviewed changes

jetfuel merged commit 4e38442 into PaddlePaddle:develop Feb 1, 2018

jetfuel deleted the addDevFrontEndDoc branch February 1, 2018 21:47

varunarora mentioned this pull request Feb 3, 2018

compile and install step #147

Closed

		@@ -0,0 +1,105 @@
		# VisualDL Web App Develop

		VisualDL has two major components. One is the Python/C++ SDK that logs the matrix during training,


		1. Create Development Server

		Once the setup up is complete. You may create a local development server to test new features or bug fixes.


		The server provided the needed data and pass to the client side to draw scalars or histograms. The users can visualize the training progress and make a better network architecture evaluation.

		This article will go over the basic web-app architecture and development steps.


		San is a JavaScript component framework that helps the developer to implement web component in MVVM architecture pattern.

		San allows you to define a self-content view model in a .san file and attach view model objects to DOM objects.


		## ECharts

		To draw the graphs we use ECharts's framework. It can pilot charts and graphs with just a few lines of code.

Add how to develop frontend documentation. #234

Add how to develop frontend documentation. #234

Conversation

jetfuel commented Jan 31, 2018

varunarora left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment