Merge pull request #1213 from tqchen/master

[DOC] refactor doc

doc/R-package/index.md

@@ -9,7 +9,7 @@ You have find XGBoost R Package!
 Get Started
 -----------
 * Checkout the [Installation Guide](../build.md) contains instructions to install xgboost, and [Tutorials](#tutorials) for examples on how to use xgboost for various tasks.
-* Please visit [walk through example](demo).
+* Please visit [walk through example](../../R-package/demo).
 
 Tutorials
 ---------

doc/cli/index.md

@@ -0,0 +1,3 @@
+# XGBoost Command Line version
+
+See [XGBoost Command Line walkthrough](https://github.com/dmlc/xgboost/blob/master/demo/binary_classification/README.md)

doc/conf.py

@@ -117,10 +117,11 @@ todo_include_todos = False
 
 # -- Options for HTML output ----------------------------------------------
 
+html_theme_path = ['_static']
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 # html_theme = 'alabaster'
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'xgboost-theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

doc/get_started/index.md

@@ -0,0 +1,80 @@
+# Get Started with XGBoost
+
+This is a quick started tutorial showing snippets for you to quickly try out xgboost
+on the demo dataset on a binary classification task.
+
+## Links to Helpful Other Resources
+- See [Installation Guide](../build.md) on how to install xgboost.
+- See [How to pages](../how_to/index.md) on various tips on using xgboost.
+- See [Tutorials](../tutorials/index.md) on tutorials on specific tasks.
+- See [Learning to use XGBoost by Examples](../../demo) for more code examples.
+
+## Python
+```python
+import xgboost as xgb
+# read in data
+dtrain = xgb.DMatrix('demo/data/agaricus.txt.train')
+dtest = xgb.DMatrix('demo/data/agaricus.txt.test')
+# specify parameters via map
+param = {'max_depth':2, 'eta':1, 'silent':1, 'objective':'binary:logistic' }
+num_round = 2
+bst = xgb.train(param, dtrain, num_round)
+# make prediction
+preds = bst.predict(dtest)
+```
+
+## R
+
+```r
+# load data
+data(agaricus.train, package='xgboost')
+data(agaricus.test, package='xgboost')
+train <- agaricus.train
+test <- agaricus.test
+# fit model
+bst <- xgboost(data = train$data, label = train$label, max.depth = 2, eta = 1, nround = 2,
+               nthread = 2, objective = "binary:logistic")
+# predict
+pred <- predict(bst, test$data)
+
+```
+
+## Julia
+```julia
+using XGBoost
+# read data
+train_X, train_Y = readlibsvm("demo/data/agaricus.txt.train", (6513, 126))
+test_X, test_Y = readlibsvm("demo/data/agaricus.txt.test", (1611, 126))
+# fit model
+num_round = 2
+bst = xgboost(train_X, num_round, label=train_Y, eta=1, max_depth=2)
+# predict
+pred = predict(bst, test_X)
+```
+
+## Scala
+```scala
+import ml.dmlc.xgboost4j.scala.DMatrix
+import ml.dmlc.xgboost4j.scala.XGBoost
+
+object XGBoostScalaExample {
+  def main(args: Array[String]) {
+    // read trainining data, available at xgboost/demo/data
+    val trainData =
+      new DMatrix("/path/to/agaricus.txt.train")
+    // define parameters
+    val paramMap = List(
+      "eta" -> 0.1,
+      "max_depth" -> 2,
+      "objective" -> "binary:logistic").toMap
+    // number of iterations
+    val round = 2
+    // train the model
+    val model = XGBoost.train(trainData, paramMap, round)
+    // run prediction
+    val predTrain = model.predict(trainData)
+    // save model to the file.
+    model.saveModel("/local/path/to/model")
+  }
+}
+```

doc/how_to/index.md

@@ -0,0 +1,16 @@
+# XGBoost How To
+
+This page contains guidelines to use and develop mxnets.
+
+## Installation
+- [How to Install XGBoost](../build.md)
+
+## Use XGBoost in Specific Ways
+- [Parameter tunning guide](param_tuning.md)
+- [Use out of core computation for large dataset](external_memory.md)
+
+## Develop and Hack XGBoost
+- [Contribute to XGBoost](contribute.md)
+
+## Frequently Ask Questions
+- [FAQ](../faq.md)

doc/index.md

@@ -1,59 +1,15 @@
 XGBoost Documentation
 =====================
-This is document of xgboost library.
-XGBoost is short for eXtreme gradient boosting. This is a library that is designed, and optimized for boosted (tree) algorithms.
-The goal of this library is to push the extreme of the computation limits of machines to provide a ***scalable***, ***portable*** and ***accurate***
-for large scale tree boosting.
-
 This document is hosted at http://xgboost.readthedocs.org/. You can also browse most of the documents in github directly.
 
 
-Package Documents
------------------
-This section contains language specific package guide.
-* [XGBoost Command Line Usage Walkthrough](../demo/binary_classification/README.md)
+These are used to generate the index used in search.
+
 * [Python Package Document](python/index.md)
 * [R Package Document](R-package/index.md)
 * [Java/Scala Package Document](jvm/index.md)
-* [XGBoost.jl Julia Package](https://github.com/dmlc/XGBoost.jl)
-
-User Guides
------------
-This section contains users guides that are general across languages.
-* [Installation Guide](build.md)
-* [Introduction to Boosted Trees](model.md)
-* [Distributed Training Tutorial](tutorial/aws_yarn.md)
-* [Frequently Asked Questions](faq.md)
-* [External Memory Version](external_memory.md)
-* [Learning to use XGBoost by Example](../demo)
-* [Parameters](parameter.md)
-* [Text input format](input_format.md)
-* [Notes on Parameter Tunning](param_tuning.md)
-
-
-Tutorials
----------
-This section contains official tutorials of XGBoost package.
-See [Awesome XGBoost](https://github.com/dmlc/xgboost/tree/master/demo) for links to mores resources.
-* [Introduction to XGBoost in R](R-package/xgboostPresentation.md) (R package)
-  - This is a general presentation about xgboost in R.
-* [Discover your data with XGBoost in R](R-package/discoverYourData.md) (R package)
-  - This tutorial explaining feature analysis in xgboost.
-* [Introduction of XGBoost in Python](python/python_intro.md) (python)
-  - This tutorial introduces the python package of xgboost
-* [Understanding XGBoost Model on Otto Dataset](../demo/kaggle-otto/understandingXGBoostModel.Rmd) (R package)
-  - This tutorial teaches you how to use xgboost to compete kaggle otto challenge.
-
-Developer Guide
----------------
-* [Contributor Guide](dev-guide/contribute.md)
-
-
-Indices and tables
-------------------
-
-```eval_rst
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-```
+* [Julia Package Document](julia/index.md)
+* [CLI Package Document](cli/index.md)
+- [Howto Documents](how_to/index.md)
+- [Get Started Documents](get_started/index.md)
+- [Tutorials](tutorials/index.md)

doc/julia/index.md

@@ -0,0 +1,3 @@
+# XGBoost.jl
+
+See [XGBoost.jl Project page](https://github.com/dmlc/XGBoost.jl)

doc/jvm/index.md

@@ -7,20 +7,24 @@ You have find XGBoost JVM Package!
 
 Installation
 ------------
-Currently, XGBoost4J only support installation from source. Building XGBoost4J using Maven requires Maven 3 or newer and Java 7+. 
+Currently, XGBoost4J only support installation from source. Building XGBoost4J using Maven requires Maven 3 or newer and Java 7+.
 
 Before you install XGBoost4J, you need to define environment variable `JAVA_HOME` as your JDK directory to ensure that your compiler can find `jni.h` correctly, since XGBoost4J relies on JNI to implement the interaction between the JVM and native libraries.
 
 After your `JAVA_HOME` is defined correctly, it is as simple as run `mvn package` under jvm-packages directory to install XGBoost4J.
 
-NOTE: XGBoost4J requires to run with Spark 1.6 or newer 
+NOTE: XGBoost4J requires to run with Spark 1.6 or newer
 
 Contents
 --------
 * [Java Overview Tutorial](java_intro.md)
+
+Resources
+---------
 * [Code Examples](https://github.com/dmlc/xgboost/tree/master/jvm-packages/xgboost4j-example)
 * [Java API Docs](http://dmlc.ml/docs/javadocs/index.html)
-* [Scala API Docs]
+
+## Scala API Docs
   * [XGBoost4J](http://dmlc.ml/docs/scaladocs/xgboost4j/index.html)
   * [XGBoost4J-Spark](http://dmlc.ml/docs/scaladocs/xgboost4j-spark/index.html)
   * [XGBoost4J-Flink](http://dmlc.ml/docs/scaladocs/xgboost4j-flink/index.html)

doc/parameter.md

@@ -72,7 +72,7 @@ Parameters for Tree Booster
     but consider set to lower number for more accurate enumeration.
   - range: (0, 1)
 * scale_pos_weight, [default=0]
-  - Control the balance of positive and negative weights, useful for unbalanced classes. A typical value to consider: sum(negative  cases) / sum(positive cases) See [Parameters Tuning](param_tuning.md) for more discussion. Also see Higgs Kaggle competition demo for examples: [R](../demo/kaggle-higgs/higgs-train.R ), [py1](../demo/kaggle-higgs/higgs-numpy.py ), [py2](../demo/kaggle-higgs/higgs-cv.py ), [py3](../demo/guide-python/cross_validation.py) 
+  - Control the balance of positive and negative weights, useful for unbalanced classes. A typical value to consider: sum(negative  cases) / sum(positive cases) See [Parameters Tuning](how_to/param_tuning.md) for more discussion. Also see Higgs Kaggle competition demo for examples: [R](../demo/kaggle-higgs/higgs-train.R ), [py1](../demo/kaggle-higgs/higgs-numpy.py ), [py2](../demo/kaggle-higgs/higgs-cv.py ), [py3](../demo/guide-python/cross_validation.py)
 
 Parameters for Linear Booster
 -----------------------------

doc/tutorials/index.md

@@ -0,0 +1,8 @@
+# XGBoost Tutorials
+
+This section contains official tutorials inside XGBoost package.
+See [Awesome XGBoost](https://github.com/dmlc/xgboost/tree/master/demo) for links to mores resources.
+
+## Contents
+- [Introduction to Boosted Trees](../model.md)
+- [Distributed XGBoost YARN on AWS](aws_yarn.md)