Fix the configuration documentation script. (#679)

Fixes #652.
Now also includes documentation for one option that was "repeated"
and not "optional".

docs/source/configuration.rst

@@ -33,70 +33,8 @@ int32 num_threads
   Not yet documented.
 
 
-cartographer.mapping.proto.MapBuilderOptions
+cartographer.mapping.pose_graph.proto.ConstraintBuilderOptions
-============================================
+==============================================================
-
-bool use_trajectory_builder_2d
-  Not yet documented.
-
-bool use_trajectory_builder_3d
-  Not yet documented.
-
-int32 num_background_threads
-  Number of threads to use for background computations.
-
-cartographer.mapping.proto.SparsePoseGraphOptions sparse_pose_graph_options
-  Not yet documented.
-
-
-cartographer.mapping.proto.SparsePoseGraphOptions
-=================================================
-
-int32 optimize_every_n_scans
-  Online loop closure: If positive, will run the loop closure while the map
-  is built.
-
-cartographer.mapping.sparse_pose_graph.proto.ConstraintBuilderOptions constraint_builder_options
-  Options for the constraint builder.
-
-double matcher_translation_weight
-  Weight used in the optimization problem for the translational component of
-  non-loop-closure scan matcher constraints.
-
-double matcher_rotation_weight
-  Weight used in the optimization problem for the rotational component of
-  non-loop-closure scan matcher constraints.
-
-cartographer.mapping.sparse_pose_graph.proto.OptimizationProblemOptions optimization_problem_options
-  Options for the optimization problem.
-
-int32 max_num_final_iterations
-  Number of iterations to use in 'optimization_problem_options' for the final
-  optimization.
-
-double global_sampling_ratio
-  Rate at which we sample a single trajectory's scans for global
-  localization.
-
-bool log_residual_histograms
-  Whether to output histograms for the pose residuals.
-
-
-cartographer.mapping.proto.TrajectoryBuilderOptions
-===================================================
-
-cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions trajectory_builder_2d_options
-  Not yet documented.
-
-cartographer.mapping_3d.proto.LocalTrajectoryBuilderOptions trajectory_builder_3d_options
-  Not yet documented.
-
-bool pure_localization
-  Not yet documented.
-
-
-cartographer.mapping.sparse_pose_graph.proto.ConstraintBuilderOptions
-=====================================================================
 
 double sampling_ratio
   A constraint will be added if the proportion of added constraints to
@@ -136,8 +74,8 @@ cartographer.mapping_3d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_m
   Not yet documented.
 
 
-cartographer.mapping.sparse_pose_graph.proto.OptimizationProblemOptions
+cartographer.mapping.pose_graph.proto.OptimizationProblemOptions
-=======================================================================
+================================================================
 
 double huber_scale
   Scaling parameter for Huber loss function.
@@ -167,6 +105,73 @@ cartographer.common.proto.CeresSolverOptions ceres_solver_options
   Not yet documented.
 
 
+cartographer.mapping.proto.MapBuilderOptions
+============================================
+
+bool use_trajectory_builder_2d
+  Not yet documented.
+
+bool use_trajectory_builder_3d
+  Not yet documented.
+
+int32 num_background_threads
+  Number of threads to use for background computations.
+
+cartographer.mapping.proto.SparsePoseGraphOptions sparse_pose_graph_options
+  Not yet documented.
+
+
+cartographer.mapping.proto.SparsePoseGraphOptions
+=================================================
+
+int32 optimize_every_n_scans
+  Online loop closure: If positive, will run the loop closure while the map
+  is built.
+
+cartographer.mapping.pose_graph.proto.ConstraintBuilderOptions constraint_builder_options
+  Options for the constraint builder.
+
+double matcher_translation_weight
+  Weight used in the optimization problem for the translational component of
+  non-loop-closure scan matcher constraints.
+
+double matcher_rotation_weight
+  Weight used in the optimization problem for the rotational component of
+  non-loop-closure scan matcher constraints.
+
+cartographer.mapping.pose_graph.proto.OptimizationProblemOptions optimization_problem_options
+  Options for the optimization problem.
+
+int32 max_num_final_iterations
+  Number of iterations to use in 'optimization_problem_options' for the final
+  optimization.
+
+double global_sampling_ratio
+  Rate at which we sample a single trajectory's scans for global
+  localization.
+
+bool log_residual_histograms
+  Whether to output histograms for the pose residuals.
+
+double global_constraint_search_after_n_seconds
+  If for the duration specified by this option no global contraint has been
+  added between two trajectories, loop closure searches will be performed
+  globally rather than in a smaller search window.
+
+
+cartographer.mapping.proto.TrajectoryBuilderOptions
+===================================================
+
+cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions trajectory_builder_2d_options
+  Not yet documented.
+
+cartographer.mapping_3d.proto.LocalTrajectoryBuilderOptions trajectory_builder_3d_options
+  Not yet documented.
+
+bool pure_localization
+  Not yet documented.
+
+
 cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions
 ===========================================================
 
@@ -353,6 +358,9 @@ double imu_gravity_time_constant
   2. from integration of angular velocities (which gets worse when the
   constant is increased) is balanced.
 
+int32 rotational_histogram_size
+  Number of histogram buckets for the rotational scan matcher.
+
 cartographer.mapping_3d.proto.SubmapsOptions submaps_options
   Not yet documented.
 
@@ -413,9 +421,12 @@ cartographer.mapping_3d.proto.RangeDataInserterOptions range_data_inserter_optio
 cartographer.mapping_3d.scan_matching.proto.CeresScanMatcherOptions
 ===================================================================
 
-double translation_weight
+double occupied_space_weight
   Scaling parameters for each cost functor.
 
+double translation_weight
+  Not yet documented.
+
 double rotation_weight
   Not yet documented.
 
@@ -437,9 +448,6 @@ int32 full_resolution_depth
   Number of full resolution grids to use, additional grids will reduce the
   resolution by half each.
 
-int32 rotational_histogram_size
-  Number of histogram buckets for the rotational scan matcher.
-
 double min_rotational_score
   Minimum score for the rotational scan matcher.
 

scripts/update_configuration_doc.py

@@ -103,7 +103,7 @@ def ParseProtoFile(proto_file):
 
     # We capture the contents of this message.
     option_comments = []
-    multiline = None
+    multiline = ''
     for line in line_iter:
       line = line.strip()
       if '}' in line:
@@ -116,21 +116,17 @@ def ParseProtoFile(proto_file):
           option_comments.append(comment)
       else:
         assert not line.startswith('required')
-        if multiline is None:
+        multiline += ' ' + line
-          if line.startswith('optional'):
-            multiline = line
-          else:
-            continue
-        else:
-          multiline += ' ' + line
         if not multiline.endswith(';'):
           continue
         assert len(multiline) < 200
-        option = multiline[8:-1].strip().rstrip('0123456789').strip()
+        option = multiline[:-1].strip().rstrip('0123456789').strip()
         assert option.endswith('=')
+        if option.startswith('repeated'):
+          option = option[8:]
         option_type, option_name = option[:-1].strip().split();
         print("  Option '%s'." % option_name)
-        multiline = None
+        multiline = ''
         message.AddOption(option_type, option_name, option_comments)
         option_comments = []
 
@@ -186,6 +182,11 @@ def GenerateDocumentation(output_file, root):
       content.extend(preceding_comments)
       content.append('')
     for option_type, option_name, option_comments in message.options:
+      # TODO(whess): For now we exclude InitialTrajectoryPose from the
+      # documentation. It is documented itself (since it has no Options suffix)
+      # and is not parsed from the Lua files.
+      if option_type in ('InitialTrajectoryPose',):
+        continue
       content.append(
           resolver.Resolve(option_type, message.package) + ' ' + option_name)
       if not option_comments: