Break API docs up into separate files.

doc/api.rst

@@ -0,0 +1,14 @@
+.. _api:
+
+API Documentation
+=================
+
+.. toctree::
+   :maxdepth: 4
+
+   api/quickstart
+   api/skll
+   api/data
+   api/experiments
+   api/learner
+   api/metrics

doc/api/data.rst

@@ -0,0 +1,24 @@
+:mod:`data` Package
+===================
+
+
+:mod:`data.featureset` Module
+-----------------------------
+
+.. automodule:: skll.data.featureset
+    :members:
+    :show-inheritance:
+
+:mod:`data.readers` Module
+--------------------------
+
+.. automodule:: skll.data.readers
+    :members:
+    :show-inheritance:
+
+:mod:`data.writers` Module
+--------------------------
+
+.. automodule:: skll.data.writers
+    :members:
+    :show-inheritance:

doc/api/experiments.rst

@@ -0,0 +1,6 @@
+:mod:`experiments` Module
+=========================
+
+.. automodule:: skll.experiments
+    :members:
+    :show-inheritance:

doc/api/learner.rst

@@ -0,0 +1,6 @@
+:mod:`learner` Module
+=====================
+
+.. automodule:: skll.learner
+    :members:
+    :show-inheritance:

doc/api/metrics.rst

@@ -0,0 +1,6 @@
+:mod:`metrics` Module
+---------------------
+
+.. automodule:: skll.metrics
+    :members:
+    :show-inheritance:

doc/api/quickstart.rst

@@ -0,0 +1,40 @@
+Quickstart
+==========
+
+Here is a quick run-down of how you accomplish common tasks.
+
+Load some a FeatureSet from a file::
+
+    from skll import Reader
+
+    example_reader = Reader.for_path('myexamples.megam')
+    train_examples = example_reader.read()
+
+
+Train a linear svm (assuming we have `train_examples`)::
+
+    from skll import Learner
+
+    learner = Learner('LinearSVC')
+    learner.train(train_examples)
+
+
+Evaluate a trained model::
+
+    test_examples = Reader.for_path('test.tsv').read()
+    conf_matrix, accuracy, prf_dict, model_params, obj_score = learner.evaluate(test_examples)
+
+
+Perform ten-fold cross-validation with a radial SVM::
+
+    learner = Learner('SVC')
+    fold_result_list, grid_search_scores = learner.cross-validate(train_examples)
+
+``fold_result_list`` in this case is a list of the results returned by
+``learner.evaluate`` for each fold, and ``grid_search_scores`` is the highest
+objective function value achieved when tuning the model.
+
+
+Generate predictions from a trained model::
+
+    predictions = learner.predict(test_examples)

doc/api/skll.rst

@@ -0,0 +1,35 @@
+:mod:`skll` Package
+===================
+
+The most useful parts of our API are available at the package level in addition
+to the module level. They are documented in both places for convenience.
+
+From :py:mod:`~skll.data` Package
+---------------------------------
+.. autoclass:: skll.FeatureSet
+    :members:
+    :show-inheritance:
+.. autoclass:: skll.Reader
+    :members:
+    :show-inheritance:
+.. autoclass:: skll.Writer
+    :members:
+    :show-inheritance:
+
+From :py:mod:`~skll.experiments` Module
+---------------------------------------
+.. autofunction:: skll.run_configuration
+
+From :py:mod:`~skll.learner` Module
+-----------------------------------
+.. autoclass:: skll.Learner
+    :members:
+    :show-inheritance:
+
+From :py:mod:`~skll.metrics` Module
+-----------------------------------
+.. autofunction:: skll.f1_score_least_frequent
+.. autofunction:: skll.kappa
+.. autofunction:: skll.kendall_tau
+.. autofunction:: skll.spearman
+.. autofunction:: skll.pearson

doc/index.rst

@@ -16,7 +16,7 @@ SKLL (pronounced "skull") provides a number of utilities to make it simpler to
 run common scikit-learn experiments with pre-generated features.
 
 There are two primary means of using SKLL: :doc:`the run_experiment script <run_experiment>`
-and :doc:`the Python API <skll>`.
+and :doc:`the Python API <api>`.
 
 
 Documentation
@@ -29,7 +29,7 @@ Documentation
    tutorial
    run_experiment
    utilities
-   skll
+   api
 
 
 Indices and tables