Documentation update

1. Make the documentation build with Sphinx 1.2
2. Update the documentation for IterationSummary to
   be Sphinx friendly.

Change-Id: I93c374987bc0597e854fbcb5a4a25dd2058607f5

docs/source/_themes/armstrong/globaltoc.html

@@ -8,4 +8,4 @@
     :license: BSD, see LICENSE for details.
 #}
 <h3><a href="{{ pathto(master_doc) }}">{{ _('Ceres Solver') }}</a></h3>
-{{ toctree() }}
+{{ toctree(includehidden=True) }}

docs/source/solving.rst

@@ -1542,95 +1542,121 @@ elimination group [LiSaad]_.
 
 .. class:: IterationSummary
 
-   :class:`IterationSummary` describes the state of the optimizer
-   after each iteration of the minimization. Note that all times are
-   wall times.
+   :class:`IterationSummary` describes the state of the minimizer at
+   the end of each iteration.
 
-   .. code-block:: c++
+.. member:: int32 IterationSummary::iteration
+
+   Current iteration number.
+
+.. member:: bool IterationSummary::step_is_valid
+
+   Step was numerically valid, i.e., all values are finite and the
+   step reduces the value of the linearized model.
+
+    **Note**: :member:`IterationSummary::step_is_valid` is `false`
+    when :member:`IterationSummary::iteration` = 0.
+
+.. member::  bool IterationSummary::step_is_nonmonotonic
+
+    Step did not reduce the value of the objective function
+    sufficiently, but it was accepted because of the relaxed
+    acceptance criterion used by the non-monotonic trust region
+    algorithm.
+
+    **Note**: :member:`IterationSummary::step_is_nonmonotonic` is
+    `false` when when :member:`IterationSummary::iteration` = 0.
+
+.. member:: bool IterationSummary::step_is_successful
+
+   Whether or not the minimizer accepted this step or not.
+
+   If the ordinary trust region algorithm is used, this means that the
+   relative reduction in the objective function value was greater than
+   :member:`Solver::Options::min_relative_decrease`. However, if the
+   non-monotonic trust region algorithm is used
+   (:member:`Solver::Options:use_nonmonotonic_steps` = `true`), then
+   even if the relative decrease is not sufficient, the algorithm may
+   accept the step and the step is declared successful.
+
+   **Note**: :member:`IterationSummary::step_is_successful` is `false`
+   when when :member:`IterationSummary::iteration` = 0.
+
+.. member:: double IterationSummary::cost
+
+   Value of the objective function.
+
+.. member:: double IterationSummary::cost_change
+
+   Change in the value of the objective function in this
+   iteration. This can be positive or negative.
+
+.. member:: double IterationSummary::gradient_max_norm
+
+   Infinity norm of the gradient vector.
+
+.. member:: double IterationSummary::gradient_norm
+
+   2-norm of the gradient vector.
+
+.. member:: double IterationSummary::step_norm
+
+   2-norm of the size of the step computed in this iteration.
+
+.. member:: double IterationSummary::relative_decrease
+
+   For trust region algorithms, the ratio of the actual change in cost
+   and the change in the cost of the linearized approximation.
+
+   This field is not used when a linear search minimizer is used.
+
+.. member:: double IterationSummary::trust_region_radius
+
+   Size of the trust region at the end of the current iteration. For
+   the Levenberg-Marquardt algorithm, the regularization parameter is
+   1.0 / member::`IterationSummary::trust_region_radius`.
+
+.. member:: double IterationSummary::eta
+
+   For the inexact step Levenberg-Marquardt algorithm, this is the
+   relative accuracy with which the step is solved. This number is
+   only applicable to the iterative solvers capable of solving linear
+   systems inexactly. Factorization-based exact solvers always have an
+   eta of 0.0.
+
+.. member:: double IterationSummary::step_size
+
+   Step sized computed by the line search algorithm.
+
+   This field is not used when a trust region minimizer is used.
+
+.. member:: int IterationSummary::line_search_function_evaluations
+
+   Number of function evaluations used by the line search algorithm.
+
+   This field is not used when a trust region minimizer is used.
+
+.. member:: int IterationSummary::linear_solver_iterations
+
+   Number of iterations taken by the linear solver to solve for the
+   trust region step.
+
+   Currently this field is not used when a line search minimizer is
+   used.
+
+.. member:: double IterationSummary::iteration_time_in_seconds
+
+   Time (in seconds) spent inside the minimizer loop in the current
+   iteration.
+
+.. member:: double IterationSummary::step_solver_time_in_seconds
+
+   Time (in seconds) spent inside the trust region step solver.
+
+.. member:: double IterationSummary::cumulative_time_in_seconds
+
+   Time (in seconds) since the user called Solve().
 
-     struct IterationSummary {
-       // Current iteration number.
-       int32 iteration;
-
-       // Step was numerically valid, i.e., all values are finite and the
-       // step reduces the value of the linearized model.
-       //
-       // Note: step_is_valid is false when iteration = 0.
-       bool step_is_valid;
-
-       // Step did not reduce the value of the objective function
-       // sufficiently, but it was accepted because of the relaxed
-       // acceptance criterion used by the non-monotonic trust region
-       // algorithm.
-       //
-       // Note: step_is_nonmonotonic is false when iteration = 0;
-       bool step_is_nonmonotonic;
-
-       // Whether or not the minimizer accepted this step or not. If the
-       // ordinary trust region algorithm is used, this means that the
-       // relative reduction in the objective function value was greater
-       // than Solver::Options::min_relative_decrease. However, if the
-       // non-monotonic trust region algorithm is used
-       // (Solver::Options:use_nonmonotonic_steps = true), then even if the
-       // relative decrease is not sufficient, the algorithm may accept the
-       // step and the step is declared successful.
-       //
-       // Note: step_is_successful is false when iteration = 0.
-       bool step_is_successful;
-
-       // Value of the objective function.
-       double cost;
-
-       // Change in the value of the objective function in this
-       // iteration. This can be positive or negative.
-       double cost_change;
-
-       // Infinity norm of the gradient vector.
-       double gradient_max_norm;
-
-       // 2-norm of the gradient vector.
-       double gradient_norm;
-
-       // 2-norm of the size of the step computed by the optimization
-       // algorithm.
-       double step_norm;
-
-       // For trust region algorithms, the ratio of the actual change in
-       // cost and the change in the cost of the linearized approximation.
-       double relative_decrease;
-
-       // Size of the trust region at the end of the current iteration. For
-       // the Levenberg-Marquardt algorithm, the regularization parameter
-       // mu = 1.0 / trust_region_radius.
-       double trust_region_radius;
-
-       // For the inexact step Levenberg-Marquardt algorithm, this is the
-       // relative accuracy with which the Newton(LM) step is solved. This
-       // number affects only the iterative solvers capable of solving
-       // linear systems inexactly. Factorization-based exact solvers
-       // ignore it.
-       double eta;
-
-       // Step sized computed by the line search algorithm.
-       double step_size;
-
-       // Number of function evaluations used by the line search algorithm.
-       int line_search_function_evaluations;
-
-       // Number of iterations taken by the linear solver to solve for the
-       // Newton step.
-       int linear_solver_iterations;
-
-       // Time (in seconds) spent inside the minimizer loop in the current
-       // iteration.
-       double iteration_time_in_seconds;
-
-       // Time (in seconds) spent inside the trust region step solver.
-       double step_solver_time_in_seconds;
-
-       // Time (in seconds) since the user called Solve().
-       double cumulative_time_in_seconds;
-    };
 
 .. class:: IterationCallback