man/docgen

   1 #!/usr/bin/env python
   2 #
   3 # Chocolate Doom self-documentation tool.  This works similar to javadoc
   4 # or doxygen, but documents command line parameters and configuration
   5 # file values, generating documentation in Unix manpage, wikitext and
   6 # plain text forms.
   7 #
   8 # Comments are read from the source code in the following form:
   9 #
  10 #   //!
  11 #   // @arg <extra arguments>
  12 #   // @category Category
  13 #   // @platform <some platform that the parameter is specific to>
  14 #   //
  15 #   // Long description of the parameter
  16 #   //
  17 #
  18 #   something_involving = M_CheckParm("-param");
  19 #
  20 # For configuration file values:
  21 #
  22 #   //! @begin_config_file myconfig.cfg
  23 #
  24 #   //!
  25 #   // Description of the configuration file value.
  26 #   //
  27 #
  28 #   CONFIG_VARIABLE_INT(my_variable,       c_variable),
  29 #
  30
  31 import sys
  32 import os
  33 import re
  34 import glob
  35 import getopt
  36
  37 # Find the maximum width of a list of parameters (for plain text output)
  38
  39 def parameter_list_width(params):
  40     w = 0
  41
  42     for p in params:
  43         pw = len(p.name) + 5
  44
  45         if p.args:
  46             pw += len(p.args)
  47
  48         if pw > w:
  49             w = pw
  50
  51     return w
  52
  53 class ConfigFile:
  54     def __init__(self, filename):
  55         self.filename = filename
  56         self.variables = []
  57
  58     def add_variable(self, variable):
  59         self.variables.append(variable)
  60
  61     def manpage_output(self):
  62         result = ".SH CONFIGURATION VARIABLES\n"
  63
  64         for v in self.variables:
  65             result += ".TP\n"
  66             result += v.manpage_output()
  67
  68         return result
  69
  70     def plaintext_output(self):
  71         result = ""
  72
  73         w = parameter_list_width(self.variables)
  74
  75         for p in self.variables:
  76             result += p.plaintext_output(w)
  77
  78         result = result.rstrip() + "\n"
  79
  80         return result
  81
  82 class Category:
  83     def __init__(self, description):
  84         self.description = description
  85         self.params = []
  86
  87     def add_param(self, param):
  88         self.params.append(param)
  89
  90     # Plain text output
  91
  92     def plaintext_output(self):
  93         result = "=== %s ===\n\n" % self.description
  94
  95         self.params.sort()
  96
  97         w = parameter_list_width(self.params)
  98
  99         for p in self.params:
 100             if p.should_show():
 101                 result += p.plaintext_output(w)
 102
 103         result = result.rstrip() + "\n"
 104
 105         return result
 106
 107     def manpage_output(self):
 108         result = ".SH " + self.description.upper() + "\n"
 109
 110         self.params.sort()
 111
 112         for p in self.params:
 113             if p.should_show():
 114                 result += ".TP\n"
 115                 result += p.manpage_output()
 116
 117         return result
 118
 119     def wiki_output(self):
 120         result = "=== %s ===\n" % self.description
 121
 122         self.params.sort()
 123
 124         for p in self.params:
 125             if p.should_show():
 126                 result += "; " + p.wiki_output() + "\n"
 127
 128         # Escape special HTML characters
 129
 130         result = result.replace("&", "&amp;")
 131         result = result.replace("<", "&lt;")
 132         result = result.replace(">", "&gt;")
 133
 134         return result
 135
 136 categories = {
 137     None:      Category("General options"),
 138     "video":   Category("Display options"),
 139     "demo":    Category("Demo options"),
 140     "net":     Category("Networking options"),
 141     "mod":     Category("Dehacked and WAD merging"),
 142     "compat":  Category("Compatibility"),
 143 }
 144
 145 wikipages = []
 146 config_files = {}
 147
 148 # Show options that are in Vanilla Doom? Or only new options?
 149
 150 show_vanilla_options = True
 151
 152 class Parameter:
 153     def __cmp__(self, other):
 154         if self.name < other.name:
 155             return -1
 156         else:
 157             return 1
 158
 159     def __init__(self):
 160         self.text = ""
 161         self.name = ""
 162         self.args = None
 163         self.platform = None
 164         self.category = None
 165         self.vanilla_option = False
 166
 167     def should_show(self):
 168         return not self.vanilla_option or show_vanilla_options
 169
 170     def add_text(self, text):
 171         if len(text) <= 0:
 172             pass
 173         elif text[0] == "@":
 174             match = re.match('@(\S+)\s*(.*)', text)
 175
 176             if not match:
 177                 raise "Malformed option line: %s" % text
 178
 179             option_type = match.group(1)
 180             data = match.group(2)
 181
 182             if option_type == "arg":
 183                 self.args = data
 184             elif option_type == "platform":
 185                 self.platform = data
 186             elif option_type == "category":
 187                 self.category = data
 188             elif option_type == "vanilla":
 189                 self.vanilla_option = True
 190             else:
 191                 raise "Unknown option type '%s'" % option_type
 192
 193         else:
 194             self.text += text + " "
 195
 196     def manpage_output(self):
 197         result = self.name
 198
 199         if self.args:
 200             result += " " + self.args
 201
 202         result = '\\fB' + result + '\\fR'
 203
 204         result += "\n"
 205
 206         if self.platform:
 207             result += "[%s only] " % self.platform
 208
 209         escaped = re.sub('\\\\', '\\\\\\\\', self.text)
 210
 211         result += escaped + "\n"
 212
 213         return result
 214
 215     def wiki_output(self):
 216         result = self.name
 217
 218         if self.args:
 219             result += " " + self.args
 220
 221         result += ": "
 222
 223         result += add_wiki_links(self.text)
 224
 225         if self.platform:
 226             result += "'''(%s only)'''" % self.platform
 227
 228         return result
 229
 230     def plaintext_output(self, w):
 231
 232         # Build the first line, with the argument on
 233
 234         line = "  " + self.name
 235         if self.args:
 236             line += " " + self.args
 237
 238         # pad up to the plaintext width
 239
 240         line += " " * (w - len(line))
 241
 242         # Build the description text
 243
 244         description = self.text
 245
 246         if self.platform:
 247             description += " (%s only)" % self.platform
 248
 249         # Build the complete text for the argument
 250         # Split the description into words and add a word at a time
 251
 252         result = ""
 253         for word in re.split('\s+', description):
 254
 255             # Break onto the next line?
 256
 257             if len(line) + len(word) + 1 > 75:
 258                 result += line + "\n"
 259                 line = " " * w
 260
 261             # Add another word
 262
 263             line += word + " "
 264
 265         result += line + "\n\n"
 266
 267         return result
 268
 269 # Read list of wiki pages
 270
 271 def read_wikipages():
 272     f = open("wikipages")
 273
 274     try:
 275         for line in f:
 276             line = line.rstrip()
 277
 278             line = re.sub('\#.*$', '', line)
 279
 280             if not re.match('^\s*$', line):
 281                 wikipages.append(line)
 282     finally:
 283         f.close()
 284
 285 # Add wiki page links
 286
 287 def add_wiki_links(text):
 288     for pagename in wikipages:
 289         page_re = re.compile('(%s)' % pagename, re.IGNORECASE)
 290     #   text = page_re.sub("SHOES", text)
 291         text = page_re.sub('[[\\1]]', text)
 292
 293     return text
 294
 295 def add_parameter(param, line, config_file):
 296
 297     # Is this documenting a command line parameter?
 298
 299     match = re.search('M_CheckParm\s*\(\s*"(.*?)"\s*\)', line)
 300
 301     if match:
 302         param.name = match.group(1)
 303         categories[param.category].add_param(param)
 304         return
 305
 306     # Documenting a configuration file variable?
 307
 308     match = re.search('CONFIG_VARIABLE_\S+\s*\(\s*(\S+?),', line)
 309
 310     if match:
 311         param.name = match.group(1)
 312         config_file.add_variable(param)
 313         return
 314
 315     raise Exception(param.text)
 316
 317 def process_file(file):
 318
 319     current_config_file = None
 320
 321     f = open(file)
 322
 323     try:
 324         param = None
 325         waiting_for_checkparm = False
 326
 327         for line in f:
 328             line = line.rstrip()
 329
 330             # Ignore empty lines
 331
 332             if re.match('\s*$', line):
 333                 continue
 334
 335             # Currently reading a doc comment?
 336
 337             if param:
 338                 # End of doc comment
 339
 340                 if not re.match('\s*//', line):
 341                     waiting_for_checkparm = True
 342
 343                 # The first non-empty line after the documentation comment
 344                 # ends must contain the thing being documented.
 345
 346                 if waiting_for_checkparm:
 347                     add_parameter(param, line, current_config_file)
 348                     param = None
 349                 else:
 350                     # More documentation text
 351
 352                     munged_line = re.sub('\s*\/\/\s*', '', line, 1)
 353                     munged_line = re.sub('\s*$', '', munged_line)
 354                     param.add_text(munged_line)
 355
 356             # Check for start of a doc comment
 357
 358             if re.search("//!", line):
 359                 match = re.search("@begin_config_file\s*(\S+)", line)
 360
 361                 if match:
 362                     # Beginning a configuration file
 363                     filename = match.group(1)
 364                     current_config_file = ConfigFile(filename)
 365                     config_files[filename] = current_config_file
 366                 else:
 367                     # Start of a normal comment
 368                     param = Parameter()
 369                     waiting_for_checkparm = False
 370     finally:
 371         f.close()
 372
 373 def process_files(dir):
 374     # Process all C source files.
 375
 376     if os.path.isdir(dir):
 377         files = glob.glob(dir + "/*.c")
 378
 379         for file in files:
 380             process_file(file)
 381     else:
 382         # Special case to allow a single file to be specified as a target
 383
 384         process_file(dir)
 385
 386 def print_template(template_file, content):
 387     f = open(template_file)
 388
 389     try:
 390         for line in f:
 391             line = line.replace("@content", content)
 392             print line.rstrip()
 393
 394     finally:
 395         f.close()
 396
 397 def manpage_output(targets, template_file):
 398
 399     content = ""
 400
 401     for t in targets:
 402         content += t.manpage_output() + "\n"
 403
 404     print_template(template_file, content)
 405
 406 def wiki_output(targets, template):
 407     read_wikipages()
 408
 409     for t in targets:
 410         print t.wiki_output()
 411
 412 def plaintext_output(targets, template_file):
 413
 414     content = ""
 415
 416     for t in targets:
 417         content += t.plaintext_output() + "\n"
 418
 419     print_template(template_file, content)
 420
 421 def usage():
 422     print "Usage: %s [-V] [-c filename ]( -m | -w | -p ) <directory>" \
 423             % sys.argv[0]
 424     print "   -c :  Provide documentation for the specified configuration file"
 425     print "   -m :  Manpage output"
 426     print "   -w :  Wikitext output"
 427     print "   -p :  Plaintext output"
 428     print "   -V :  Don't show Vanilla Doom options"
 429     sys.exit(0)
 430
 431 # Parse command line
 432
 433 opts, args = getopt.getopt(sys.argv[1:], "m:wp:c:V")
 434
 435 output_function = None
 436 template = None
 437 doc_config_file = None
 438
 439 for opt in opts:
 440     if opt[0] == "-m":
 441         output_function = manpage_output
 442         template = opt[1]
 443     elif opt[0] == "-w":
 444         output_function = wiki_output
 445     elif opt[0] == "-p":
 446         output_function = plaintext_output
 447         template = opt[1]
 448     elif opt[0] == "-V":
 449         show_vanilla_options = False
 450     elif opt[0] == "-c":
 451         doc_config_file = opt[1]
 452
 453 if output_function == None or len(args) != 1:
 454     usage()
 455 else:
 456
 457     # Process specified files
 458
 459     process_files(args[0])
 460
 461     # Build a list of things to document
 462
 463     documentation_targets = []
 464
 465     if doc_config_file:
 466         documentation_targets.append(config_files[doc_config_file])
 467     else:
 468         documentation_targets.append(categories[None])
 469
 470         for c in categories:
 471             if c != None:
 472                 documentation_targets.append(categories[c])
 473
 474     # Generate the output
 475
 476     output_function(documentation_targets, template)
 477