Add resolution of option types to the documentation script. (#180)
parent
1c433e6f3a
commit
1f27268664
|
@ -62,19 +62,19 @@ cartographer.mapping.proto.MapBuilderOptions
|
||||||
bool use_trajectory_builder_2d
|
bool use_trajectory_builder_2d
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
mapping_2d.proto.LocalTrajectoryBuilderOptions trajectory_builder_2d_options
|
cartographer.mapping_2d.proto.LocalTrajectoryBuilderOptions trajectory_builder_2d_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
bool use_trajectory_builder_3d
|
bool use_trajectory_builder_3d
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
mapping_3d.proto.LocalTrajectoryBuilderOptions trajectory_builder_3d_options
|
cartographer.mapping_3d.proto.LocalTrajectoryBuilderOptions trajectory_builder_3d_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
int32 num_background_threads
|
int32 num_background_threads
|
||||||
Number of threads to use for background computations.
|
Number of threads to use for background computations.
|
||||||
|
|
||||||
SparsePoseGraphOptions sparse_pose_graph_options
|
cartographer.mapping.proto.SparsePoseGraphOptions sparse_pose_graph_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
|
|
||||||
|
@ -85,10 +85,10 @@ int32 optimize_every_n_scans
|
||||||
Online loop closure: If positive, will run the loop closure while the map
|
Online loop closure: If positive, will run the loop closure while the map
|
||||||
is built.
|
is built.
|
||||||
|
|
||||||
mapping.sparse_pose_graph.proto.ConstraintBuilderOptions constraint_builder_options
|
cartographer.mapping.sparse_pose_graph.proto.ConstraintBuilderOptions constraint_builder_options
|
||||||
Options for the constraint builder.
|
Options for the constraint builder.
|
||||||
|
|
||||||
mapping.sparse_pose_graph.proto.OptimizationProblemOptions optimization_problem_options
|
cartographer.mapping.sparse_pose_graph.proto.OptimizationProblemOptions optimization_problem_options
|
||||||
Options for the optimization problem.
|
Options for the optimization problem.
|
||||||
|
|
||||||
int32 max_num_final_iterations
|
int32 max_num_final_iterations
|
||||||
|
@ -110,7 +110,7 @@ double sampling_ratio
|
||||||
double max_constraint_distance
|
double max_constraint_distance
|
||||||
Threshold for poses to be considered near a submap.
|
Threshold for poses to be considered near a submap.
|
||||||
|
|
||||||
sensor.proto.AdaptiveVoxelFilterOptions adaptive_voxel_filter_options
|
cartographer.sensor.proto.AdaptiveVoxelFilterOptions adaptive_voxel_filter_options
|
||||||
Voxel filter used to compute a sparser point cloud for matching.
|
Voxel filter used to compute a sparser point cloud for matching.
|
||||||
|
|
||||||
double min_score
|
double min_score
|
||||||
|
@ -126,16 +126,16 @@ double lower_covariance_eigenvalue_bound
|
||||||
bool log_matches
|
bool log_matches
|
||||||
If enabled, logs information of loop-closing constraints for debugging.
|
If enabled, logs information of loop-closing constraints for debugging.
|
||||||
|
|
||||||
mapping_2d.scan_matching.proto.FastCorrelativeScanMatcherOptions fast_correlative_scan_matcher_options
|
cartographer.mapping_2d.scan_matching.proto.FastCorrelativeScanMatcherOptions fast_correlative_scan_matcher_options
|
||||||
Options for the internally used scan matchers.
|
Options for the internally used scan matchers.
|
||||||
|
|
||||||
mapping_2d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options
|
cartographer.mapping_2d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
mapping_3d.scan_matching.proto.FastCorrelativeScanMatcherOptions fast_correlative_scan_matcher_options_3d
|
cartographer.mapping_3d.scan_matching.proto.FastCorrelativeScanMatcherOptions fast_correlative_scan_matcher_options_3d
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
mapping_3d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options_3d
|
cartographer.mapping_3d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options_3d
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
|
|
||||||
|
@ -160,7 +160,7 @@ double consecutive_scan_rotation_penalty_factor
|
||||||
bool log_solver_summary
|
bool log_solver_summary
|
||||||
If true, the Ceres solver summary will be logged for every optimization.
|
If true, the Ceres solver summary will be logged for every optimization.
|
||||||
|
|
||||||
common.proto.CeresSolverOptions ceres_solver_options
|
cartographer.common.proto.CeresSolverOptions ceres_solver_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
|
|
||||||
|
@ -207,16 +207,16 @@ bool use_online_correlative_scan_matching
|
||||||
Whether to solve the online scan matching first using the correlative scan
|
Whether to solve the online scan matching first using the correlative scan
|
||||||
matcher to generate a good starting point for Ceres.
|
matcher to generate a good starting point for Ceres.
|
||||||
|
|
||||||
sensor.proto.AdaptiveVoxelFilterOptions adaptive_voxel_filter_options
|
cartographer.sensor.proto.AdaptiveVoxelFilterOptions adaptive_voxel_filter_options
|
||||||
Voxel filter used to compute a sparser point cloud for matching.
|
Voxel filter used to compute a sparser point cloud for matching.
|
||||||
|
|
||||||
scan_matching.proto.RealTimeCorrelativeScanMatcherOptions real_time_correlative_scan_matcher_options
|
cartographer.mapping_2d.scan_matching.proto.RealTimeCorrelativeScanMatcherOptions real_time_correlative_scan_matcher_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options
|
cartographer.mapping_2d.scan_matching.proto.CeresScanMatcherOptions ceres_scan_matcher_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
mapping_3d.proto.MotionFilterOptions motion_filter_options
|
cartographer.mapping_3d.proto.MotionFilterOptions motion_filter_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
double imu_gravity_time_constant
|
double imu_gravity_time_constant
|
||||||
|
@ -230,7 +230,7 @@ double imu_gravity_time_constant
|
||||||
int32 num_odometry_states
|
int32 num_odometry_states
|
||||||
Maximum number of previous odometry states to keep.
|
Maximum number of previous odometry states to keep.
|
||||||
|
|
||||||
mapping_2d.proto.SubmapsOptions submaps_options
|
cartographer.mapping_2d.proto.SubmapsOptions submaps_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
bool use_imu_data
|
bool use_imu_data
|
||||||
|
@ -254,7 +254,7 @@ int32 num_laser_fans
|
||||||
bool output_debug_images
|
bool output_debug_images
|
||||||
If enabled, submap%d.png images are written for debugging.
|
If enabled, submap%d.png images are written for debugging.
|
||||||
|
|
||||||
LaserFanInserterOptions laser_fan_inserter_options
|
cartographer.mapping_2d.proto.LaserFanInserterOptions laser_fan_inserter_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
|
|
||||||
|
@ -273,7 +273,7 @@ double rotation_weight
|
||||||
double covariance_scale
|
double covariance_scale
|
||||||
Scale applied to the covariance estimate from Ceres.
|
Scale applied to the covariance estimate from Ceres.
|
||||||
|
|
||||||
common.proto.CeresSolverOptions ceres_solver_options
|
cartographer.common.proto.CeresSolverOptions ceres_solver_options
|
||||||
Configure the Ceres solver. See the Ceres documentation for more
|
Configure the Ceres solver. See the Ceres documentation for more
|
||||||
information: https://code.google.com/p/ceres-solver/
|
information: https://code.google.com/p/ceres-solver/
|
||||||
|
|
||||||
|
@ -318,10 +318,10 @@ bool use_online_correlative_scan_matching
|
||||||
Whether to solve the online scan matching first using the correlative scan
|
Whether to solve the online scan matching first using the correlative scan
|
||||||
matcher to generate a good starting point for Ceres.
|
matcher to generate a good starting point for Ceres.
|
||||||
|
|
||||||
mapping_2d.scan_matching.proto.RealTimeCorrelativeScanMatcherOptions real_time_correlative_scan_matcher_options
|
cartographer.mapping_2d.scan_matching.proto.RealTimeCorrelativeScanMatcherOptions real_time_correlative_scan_matcher_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
kalman_filter.proto.PoseTrackerOptions pose_tracker_options
|
cartographer.kalman_filter.proto.PoseTrackerOptions pose_tracker_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
double odometer_translational_variance
|
double odometer_translational_variance
|
||||||
|
@ -409,7 +409,7 @@ int32 num_laser_fans
|
||||||
number of scans inserted: First for initialization without being matched
|
number of scans inserted: First for initialization without being matched
|
||||||
against, then while being matched.
|
against, then while being matched.
|
||||||
|
|
||||||
LaserFanInserterOptions laser_fan_inserter_options
|
cartographer.mapping_3d.proto.LaserFanInserterOptions laser_fan_inserter_options
|
||||||
Not yet documented.
|
Not yet documented.
|
||||||
|
|
||||||
|
|
||||||
|
@ -428,7 +428,7 @@ double covariance_scale
|
||||||
bool only_optimize_yaw
|
bool only_optimize_yaw
|
||||||
Whether only to allow changes to yaw, keeping roll/pitch constant.
|
Whether only to allow changes to yaw, keeping roll/pitch constant.
|
||||||
|
|
||||||
common.proto.CeresSolverOptions ceres_solver_options
|
cartographer.common.proto.CeresSolverOptions ceres_solver_options
|
||||||
Configure the Ceres solver. See the Ceres documentation for more
|
Configure the Ceres solver. See the Ceres documentation for more
|
||||||
information: https://code.google.com/p/ceres-solver/
|
information: https://code.google.com/p/ceres-solver/
|
||||||
|
|
||||||
|
|
|
@ -48,19 +48,10 @@ SUFFIX = """
|
||||||
NODOC = 'Not yet documented.'
|
NODOC = 'Not yet documented.'
|
||||||
|
|
||||||
|
|
||||||
def ForEachProtoFile(root, callback):
|
|
||||||
for dirpath, dirnames, filenames in os.walk(root):
|
|
||||||
for name in filenames:
|
|
||||||
if name.endswith('.proto'):
|
|
||||||
path = os.path.join(dirpath, name)
|
|
||||||
print("Found '%s'..." % path)
|
|
||||||
assert not os.path.islink(path)
|
|
||||||
callback(io.open(path, encoding='UTF-8'))
|
|
||||||
|
|
||||||
|
|
||||||
class Message(object):
|
class Message(object):
|
||||||
def __init__(self, name, preceding_comments):
|
def __init__(self, name, package, preceding_comments):
|
||||||
self.name = name
|
self.name = name
|
||||||
|
self.package = package
|
||||||
self.preceding_comments = preceding_comments
|
self.preceding_comments = preceding_comments
|
||||||
self.trailing_comments = None
|
self.trailing_comments = None
|
||||||
self.options = []
|
self.options = []
|
||||||
|
@ -68,8 +59,8 @@ class Message(object):
|
||||||
def AddTrailingComments(self, comments):
|
def AddTrailingComments(self, comments):
|
||||||
self.trailing_comments = comments
|
self.trailing_comments = comments
|
||||||
|
|
||||||
def AddOption(self, name, comments):
|
def AddOption(self, option_type, name, comments):
|
||||||
self.options.append((name, comments))
|
self.options.append((option_type, name, comments))
|
||||||
|
|
||||||
|
|
||||||
def ParseProtoFile(proto_file):
|
def ParseProtoFile(proto_file):
|
||||||
|
@ -107,7 +98,7 @@ def ParseProtoFile(proto_file):
|
||||||
# We reached the end of file.
|
# We reached the end of file.
|
||||||
break
|
break
|
||||||
print(" Found '%s'." % message_name)
|
print(" Found '%s'." % message_name)
|
||||||
message = Message(message_name, message_comments)
|
message = Message(message_name, package, message_comments)
|
||||||
message_list.append(message)
|
message_list.append(message)
|
||||||
|
|
||||||
# We capture the contents of this message.
|
# We capture the contents of this message.
|
||||||
|
@ -135,27 +126,68 @@ def ParseProtoFile(proto_file):
|
||||||
if not multiline.endswith(';'):
|
if not multiline.endswith(';'):
|
||||||
continue
|
continue
|
||||||
assert len(multiline) < 200
|
assert len(multiline) < 200
|
||||||
option_name = multiline[8:-1].strip().rstrip('0123456789').strip()
|
option = multiline[8:-1].strip().rstrip('0123456789').strip()
|
||||||
assert option_name.endswith('=')
|
assert option.endswith('=')
|
||||||
option_name = option_name[:-1].strip();
|
option_type, option_name = option[:-1].strip().split();
|
||||||
print(" Option '%s'." % option_name)
|
print(" Option '%s'." % option_name)
|
||||||
multiline = None
|
multiline = None
|
||||||
message.AddOption(option_name, option_comments)
|
message.AddOption(option_type, option_name, option_comments)
|
||||||
option_comments = []
|
option_comments = []
|
||||||
|
|
||||||
return message_list
|
return message_list
|
||||||
|
|
||||||
|
|
||||||
def GenerateDocumentation(output_dict, proto_file):
|
def ParseProtoFilesRecursively(root):
|
||||||
for message in ParseProtoFile(proto_file):
|
"""Recursively parses all proto files into a list of Message objects."""
|
||||||
|
message_list = []
|
||||||
|
for dirpath, dirnames, filenames in os.walk(root):
|
||||||
|
for name in filenames:
|
||||||
|
if name.endswith('.proto'):
|
||||||
|
path = os.path.join(dirpath, name)
|
||||||
|
print("Found '%s'..." % path)
|
||||||
|
assert not os.path.islink(path)
|
||||||
|
message_list.extend(ParseProtoFile(io.open(path, encoding='UTF-8')))
|
||||||
|
return message_list
|
||||||
|
|
||||||
|
|
||||||
|
class ResolutionError(Exception):
|
||||||
|
"""Raised when resolving a message name fails."""
|
||||||
|
|
||||||
|
|
||||||
|
class Resolver(object):
|
||||||
|
def __init__(self, name_set):
|
||||||
|
self.name_set = set(iter(name_set))
|
||||||
|
|
||||||
|
def Resolve(self, message_name, package_name):
|
||||||
|
if message_name in ('bool', 'double', 'float', 'int32'):
|
||||||
|
return message_name
|
||||||
|
if message_name.startswith('.'):
|
||||||
|
return message_name[1:]
|
||||||
|
package = package_name.split('.')
|
||||||
|
for levels in range(len(package), -1, -1):
|
||||||
|
candidate = '.'.join(package[0:levels]) + '.' + message_name
|
||||||
|
if candidate in self.name_set:
|
||||||
|
return candidate
|
||||||
|
raise ResolutionError(
|
||||||
|
'Resolving %s in %s failed.' % (message_name, package_name))
|
||||||
|
|
||||||
|
|
||||||
|
def GenerateDocumentation(output_file, root):
|
||||||
|
"""Recursively generates documentation, sorts and writes it."""
|
||||||
|
message_list = ParseProtoFilesRecursively(root)
|
||||||
|
resolver = Resolver(message.name for message in message_list)
|
||||||
|
|
||||||
|
output_dict = {}
|
||||||
|
for message in message_list:
|
||||||
content = [message.name, '=' * len(message.name), '']
|
content = [message.name, '=' * len(message.name), '']
|
||||||
assert message.name not in output_dict
|
assert message.name not in output_dict
|
||||||
output_dict[message.name] = content
|
output_dict[message.name] = content
|
||||||
if message.preceding_comments:
|
if message.preceding_comments:
|
||||||
content.extend(preceding_comments)
|
content.extend(preceding_comments)
|
||||||
content.append('')
|
content.append('')
|
||||||
for option_name, option_comments in message.options:
|
for option_type, option_name, option_comments in message.options:
|
||||||
content.append(option_name)
|
content.append(
|
||||||
|
resolver.Resolve(option_type, message.package) + ' ' + option_name)
|
||||||
if not option_comments:
|
if not option_comments:
|
||||||
option_comments.append(NODOC)
|
option_comments.append(NODOC)
|
||||||
for comment in option_comments:
|
for comment in option_comments:
|
||||||
|
@ -165,13 +197,6 @@ def GenerateDocumentation(output_dict, proto_file):
|
||||||
content.extend(message.trailing_comments)
|
content.extend(message.trailing_comments)
|
||||||
content.append('')
|
content.append('')
|
||||||
|
|
||||||
|
|
||||||
def GenerateDocumentationRecursively(output_file, root):
|
|
||||||
"""Recursively generates documentation, sorts and writes it."""
|
|
||||||
output_dict = {}
|
|
||||||
def callback(proto_file):
|
|
||||||
GenerateDocumentation(output_dict, proto_file)
|
|
||||||
ForEachProtoFile(root, callback)
|
|
||||||
output = ['\n'.join(doc) for key, doc in sorted(list(output_dict.items()))]
|
output = ['\n'.join(doc) for key, doc in sorted(list(output_dict.items()))]
|
||||||
print('\n\n'.join(output), file=output_file)
|
print('\n\n'.join(output), file=output_file)
|
||||||
|
|
||||||
|
@ -181,7 +206,7 @@ def main():
|
||||||
assert not os.path.islink(ROOT) and os.path.isdir(ROOT)
|
assert not os.path.islink(ROOT) and os.path.isdir(ROOT)
|
||||||
output_file = io.open(TARGET, mode='w', encoding='UTF-8', newline='\n')
|
output_file = io.open(TARGET, mode='w', encoding='UTF-8', newline='\n')
|
||||||
output_file.write(PREFIX)
|
output_file.write(PREFIX)
|
||||||
GenerateDocumentationRecursively(output_file, ROOT)
|
GenerateDocumentation(output_file, ROOT)
|
||||||
output_file.write(SUFFIX)
|
output_file.write(SUFFIX)
|
||||||
output_file.close()
|
output_file.close()
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue