Browse Source

HUE-8888 [docs] Move common dev section to the bottom of the page

Romain 6 years ago
parent
commit
8b848a3675
1 changed files with 123 additions and 156 deletions
  1. 123 156
      docs/docs-site/content/developer/development/_index.md

+ 123 - 156
docs/docs-site/content/developer/development/_index.md

@@ -8,7 +8,7 @@ weight: 1
 This section goes into greater detail on how to build and reuse the components of Hue.
 
 
-## Building
+## Quick Start
 
 ### Dependencies
 
@@ -21,7 +21,7 @@ This section goes into greater detail on how to build and reuse the components o
 * [Bootstrap](http://twitter.github.com/bootstrap/)
 * [Knockout js](http://knockoutjs.com/)
 
-### Quick Start
+### Build & Start
 
 Build once:
 
@@ -47,131 +47,6 @@ your MySQL setup):
     password=secretpassword
     name=hue
 
-### Dev Docker
-
-Try basic changes in Hue without compiling it locally:
-
-    git clone https://github.com/cloudera/hue.git
-    cd hue
-    cp desktop/conf/pseudo-distributed.ini.tmpl desktop/conf/pseudo-distributed.ini
-
-Then edit the `[[database]]` section to specify a proper database, here MySql:
-
-    host=127.0.0.1 # Not localhost if Docker
-    engine=mysql
-    user=hue
-    password=hue
-    name=huedb
-
-Then map the local Hue source code into the running container (so that local edits are seen in the running Hue):
-
-    sudo docker run -it -v $PWD/apps:/usr/share/hue/apps -v $PWD/desktop:/usr/share/hue/desktop -v $PWD/desktop/conf/pseudo-distributed.ini:/usr/share/hue/desktop/conf/z-hue.ini --network="host" gethue/hue
-
-Note: code updates won’t be seen after the Docker container runs. For this Hue would need to be started in dev server mode by replacing the [line](https://github.com/cloudera/hue/blob/master/tools/docker/hue/startup.sh#L5) by
-
-    ./build/env/bin/hue runserver 0.0.0.0:8888
-
-and recompiling the Docker image. It will then auto-restart on Python code changes. For JavaScript, those would need to be [compiled](//developer/development/#javascript).
-
-### Javascript
-
-The javascript files are currently being migrated to webpack bundles, during this process some files will live under src/desktop/static/ and some will live under src/dekstop/js
-
-For changes to the files under src/desktop/js the following applies:
-
-First make sure all third-party dependencies defined in package.json are installed into node_modules/
-
-    npm install
-
-Also run this after making changes to package.json, adding new third-party dependencies etc.
-
-To generate the js bundles run:
-
-    npm run webpack
-    npm run webpack-workers
-    npm run webpack-login
-
-During development the bundles can be autogenerated when it detects changes to the .js files, for this run:
-
-    npm run dev
-
-Before sending a review with changes to the bundles run:
-
-    npm run lint-fix
-
-and possibly fix any issues it might report.
-
-### Documentation
-
-Install [Hugo](https://gohugo.io/getting-started/quick-start/).
-
-Build it and see live changes:
-
-    hugo serve
-
-### CSS / LESS
-
-After changing the CSS in a .less file, rebuilding with:
-
-    make css
-
-### SQL Autocomplete
-
-Install a patched jison:
-
-    git clone https://github.com/JohanAhlen/jison
-    cd jison
-    npm install -g .
-
-Then run:
-
-    make sql-all-parsers
-
-### Ace Editor
-
-After modifying files under tools/ace-editor run the following to build ace.js
-
-    npm install
-    make ace
-
-### Embedded language references
-
-The tools for generating the embedded language reference manuals can be found under `hue/tools/sql-docs/`
-
-#### Hive
-The Hive documentation is generated directly from the Hive wiki by using an exported epub file.
-
-1. Goto https://cwiki.apache.org/confluence/display/Hive/LanguageManual
-2. Click the three dots '...' in the upper right corner
-3. Click 'Export to EPUB'
-4. In the Hue folder run:
-
-        node tools/sql-docs/hiveExtractor.js --epub /path/to/epub/file
-
-#### Impala
-The Impala documentation is generated from the ditamap files in the Impala GitHub repo.
-
-1. Clone the Impala repo next to hue from https://github.com/apache/impala
-2. In the Hue folder run:
-
-        node tools/sql-docs/docExtractor.js -c hue -f ../impala/docs/ -d impala_langref.ditamap,impala_keydefs.ditamap,impala.ditamap -o desktop/core/src/desktop/static/desktop/docs/impala/ -m desktop/core/src/desktop/templates/impala_doc_index.mako
-
-### Internationalization
-
-How to update all the messages and compile them:
-
-    make locales
-
-How to update and compile the messages of one app:
-
-    cd apps/beeswax
-    make compile-locale
-
-How to create a new locale for an app:
-
-    cd $APP_ROOT/src/$APP_NAME/locale
-    $HUE_ROOT/build/env/bin/pybabel init -D django -i en_US.pot -d . -l fr
-
 ### Dev environment
 
 #### Visual Code
@@ -555,46 +430,44 @@ In a nutshell, front-end development in Hue is using
 [Knockout js](http://knockoutjs.com/) to layout your app and script the custom
 interactions.
 
-### Node.js
+### Javascript
+
+The javascript files are currently being migrated to webpack bundles, during this process some files will live under src/desktop/static/ and some will live under src/dekstop/js
+
+For changes to the files under src/desktop/js the following applies:
+
+First make sure all third-party dependencies defined in package.json are installed into node_modules/
+
+    npm install
+
+Also run this after making changes to package.json, adding new third-party dependencies etc.
+
+To generate the js bundles run:
+
+    npm run webpack
+    npm run webpack-workers
+    npm run webpack-login
 
 During development the bundles can be autogenerated when it detects changes to the .js files, for this run:
 
     npm run dev
 
-### CSS Styles
+Before sending a review with changes to the bundles run:
+
+    npm run lint-fix
+
+and possibly fix any issues it might report.
+
+### CSS / LESS
 
 Hue uses [Bootstrap](http://twitter.github.com/bootstrap/) version 2.0 CSS
 styles and layouts. They are highly reusable and flexible. Your app doesn't
 have to use these styles, but if you do, it'll save you some time and make your
 app look at home in Hue.
 
-On top of the standard Bootstrap styles, Hue defines a small set of custom
-styles in *desktop/core/static/css/jhue.css*.
-
-### Defining Styles
-
-When you create your application it will provision a CSS file for you in the
-*static/css* directory. For organization purposes, your styles should go here
-(and any images you have should go in *static/art*). Your app's name will be a
-class that is assigned to the root of your app in the DOM. So if you created an
-app called "calculator" then every window you create for your app will have the
-class "calculator".  Every style you define should be prefixed with this to
-prevent you from accidentally colliding with the framework style. Examples:
-
-    /* the right way: */
-    .calculator p {
-      /* all my paragraphs should have a margin of 8px */
-      margin: 8px;
-      /* and a background from my art directory */
-      background: url(../art/paragraph.gif);
-    }
-    /* the wrong way: */
-    p {
-      /* woops; we're styling all the paragraphs on the page, affecting
-         the common header! */
-      margin: 8px;
-      background: url(../art/paragraph.gif);
-    }
+After changing the CSS in a .less file, rebuilding with:
+
+    make css
 
 ### Icons
 
@@ -900,3 +773,97 @@ Release:
 
 
 Then send release notes to the [Forum](https://discourse.gethue.com/), [hue-user](https://groups.google.com/a/cloudera.org/forum/#!forum/hue-user), https://twitter.com/gethue!
+
+## Building
+
+### Dev Docker
+
+Try basic changes in Hue without compiling it locally:
+
+    git clone https://github.com/cloudera/hue.git
+    cd hue
+    cp desktop/conf/pseudo-distributed.ini.tmpl desktop/conf/pseudo-distributed.ini
+
+Then edit the `[[database]]` section to specify a proper database, here MySql:
+
+    host=127.0.0.1 # Not localhost if Docker
+    engine=mysql
+    user=hue
+    password=hue
+    name=huedb
+
+Then map the local Hue source code into the running container (so that local edits are seen in the running Hue):
+
+    sudo docker run -it -v $PWD/apps:/usr/share/hue/apps -v $PWD/desktop:/usr/share/hue/desktop -v $PWD/desktop/conf/pseudo-distributed.ini:/usr/share/hue/desktop/conf/z-hue.ini --network="host" gethue/hue
+
+Note: code updates won’t be seen after the Docker container runs. For this Hue would need to be started in dev server mode by replacing the [line](https://github.com/cloudera/hue/blob/master/tools/docker/hue/startup.sh#L5) by
+
+    ./build/env/bin/hue runserver 0.0.0.0:8888
+
+and recompiling the Docker image. It will then auto-restart on Python code changes. For JavaScript, those would need to be [compiled](//developer/development/#javascript).
+
+
+### Documentation
+
+Install [Hugo](https://gohugo.io/getting-started/quick-start/).
+
+Build it and see live changes:
+
+    hugo serve
+
+### SQL Autocomplete
+
+Install a patched jison:
+
+    git clone https://github.com/JohanAhlen/jison
+    cd jison
+    npm install -g .
+
+Then run:
+
+    make sql-all-parsers
+
+### Ace Editor
+
+After modifying files under tools/ace-editor run the following to build ace.js
+
+    npm install
+    make ace
+
+### Embedded language references
+
+The tools for generating the embedded language reference manuals can be found under `hue/tools/sql-docs/`
+
+#### Hive
+The Hive documentation is generated directly from the Hive wiki by using an exported epub file.
+
+1. Goto https://cwiki.apache.org/confluence/display/Hive/LanguageManual
+2. Click the three dots '...' in the upper right corner
+3. Click 'Export to EPUB'
+4. In the Hue folder run:
+
+        node tools/sql-docs/hiveExtractor.js --epub /path/to/epub/file
+
+#### Impala
+The Impala documentation is generated from the ditamap files in the Impala GitHub repo.
+
+1. Clone the Impala repo next to hue from https://github.com/apache/impala
+2. In the Hue folder run:
+
+        node tools/sql-docs/docExtractor.js -c hue -f ../impala/docs/ -d impala_langref.ditamap,impala_keydefs.ditamap,impala.ditamap -o desktop/core/src/desktop/static/desktop/docs/impala/ -m desktop/core/src/desktop/templates/impala_doc_index.mako
+
+### Internationalization
+
+How to update all the messages and compile them:
+
+    make locales
+
+How to update and compile the messages of one app:
+
+    cd apps/beeswax
+    make compile-locale
+
+How to create a new locale for an app:
+
+    cd $APP_ROOT/src/$APP_NAME/locale
+    $HUE_ROOT/build/env/bin/pybabel init -D django -i en_US.pot -d . -l fr