Add dump_format=json option (#1726)

* Add format to the params accepted by DumpModel

Currently, only the test format is supported when trying to dump
a model. The plan is to add more such formats like JSON which are
easy to read and/or parse by machines. And to make the interface
for this even more generic to allow other formats to be added.

Hence, we make some modifications to make these function generic
and accept a new parameter "format" which signifies the format of
the dump to be created.

* Fix typos and errors in docs

* plugin: Mention all the register macros available

Document the register macros currently available to the plugin
writers so they know what exactly can be extended using hooks.

* sparce_page_source: Use same arg name in .h and .cc

* gbm: Add JSON dump

The dump_format argument can be used to specify what type
of dump file should be created. Add functionality to dump
gblinear and gbtree into a JSON file.

The JSON file has an array, each item is a JSON object for the tree.
For gblinear:
 - The item is the bias and weights vectors
For gbtree:
 - The item is the root node. The root node has a attribute "children"
   which holds the children nodes. This happens recursively.

* core.py: Add arg dump_format for get_dump()

plugin/README.md

@@ -2,16 +2,17 @@ XGBoost Plugins Modules
 =======================
 This folder contains plugin modules to xgboost that can be optionally installed.
 The plugin system helps us to extend xgboost with additional features,
-and add experimental features that may not yet ready to be included in main project.
+and add experimental features that may not yet be ready to be included in the
+main project.
 
 To include a certain plugin, say ```plugin_a```, you only need to add the following line to the config.mk.
 
 ```makefile
-# Add plugin by include the plugin in config
+# Add plugin by including the plugin in config.mk
 XGB_PLUGINS += plugin/plugin_a/plugin.mk
 ```
 
-Then rebuild libxgboost by typing make, you can get a new library with the plugin enabled.
+Then rebuild libxgboost by typing ```make```, you can get a new library with the plugin enabled.
 
 Link Static XGBoost Library with Plugins
 ----------------------------------------
@@ -20,7 +21,7 @@ If you only use ```libxgboost.so```(this include python and other bindings),
 you can ignore this section.
 
 When you want to link ```libxgboost.a``` with additional plugins included,
-you will need to enabled whole archeive via The following option.
+you will need to enabled whole archive via The following option.
 ```bash
 --whole-archive libxgboost.a --no-whole-archive
 ```
@@ -30,3 +31,21 @@ Write Your Own Plugin
 You can plugin your own modules to xgboost by adding code to this folder,
 without modification to the main code repo.
 The [example](example) folder provides an example to write a plugin.
+
+List of register functions
+--------------------------
+A plugin has to register a new functionality to xgboost to be able to use it.
+The register macros available to plugin writers are:
+
+ - XGBOOST_REGISTER_METRIC - Register an evaluation metric
+ - XGBOOST_REGISTER_GBM - Register a new gradient booster that learns through
+   gradient statistics
+ - XGBOOST_REGISTER_OBJECTIVE - Register a new objective function used by xgboost
+ - XGBOOST_REGISTER_TREE_UPDATER - Register a new tree-updater which updates
+   the tree given the gradient information
+
+And from dmlc-core:
+
+ - DMLC_REGISTER_PARAMETER - Register a set of parameter for a specific usecase
+ - DMLC_REGISTER_DATA_PARSER - Register a data parser where the data can be
+   represented by a URL. This is used by DMatrix.

plugin/example/README.md

@@ -2,10 +2,10 @@ XGBoost Plugin Example
 ======================
 This folder provides an example of xgboost plugin.
 
-There are three steps you need to to do to add plugin to xgboost
+There are three steps you need to do to add a plugin to xgboost
 - Create your source .cc file, implement a new extension
   - In this example [custom_obj.cc](custom_obj.cc)
-- Register this extension to xgboost via registration macr
+- Register this extension to xgboost via a registration macro
   - In this example ```XGBOOST_REGISTER_OBJECTIVE``` in [this line](custom_obj.cc#L75)
 - Create a [plugin.mk](plugin.mk) on this folder