docgen 15.7 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
#!/usr/bin/env python
# 
# Chocolate Doom self-documentation tool.  This works similar to javadoc
# or doxygen, but documents command line parameters and configuration
# file values, generating documentation in Unix manpage, wikitext and
# plain text forms.
#
# Comments are read from the source code in the following form:
#
#   //!
#   // @arg <extra arguments>
#   // @category Category
#   // @platform <some platform that the parameter is specific to>
#   //
#   // Long description of the parameter
#   //
#
#   something_involving = M_CheckParm("-param");
#
# For configuration file values:
#
#   //! @begin_config_file myconfig
#
#   //!
#   // Description of the configuration file value.
#   //
#
#   CONFIG_VARIABLE_INT(my_variable,       c_variable),
#

import io
import sys
import os
import re
import glob
import getopt

38
TEXT_WRAP_WIDTH = 78
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
INCLUDE_STATEMENT_RE = re.compile("@include\s+(\S+)")

# Use appropriate stdout function for Python 2 or 3

def stdout(buf):
    if sys.version_info.major < 3:
        sys.stdout.write(buf)
    else:
        sys.stdout.buffer.write(buf)

# Find the maximum width of a list of parameters (for plain text output)

def parameter_list_width(params):
    w = 0

    for p in params:
        pw = len(p.name) + 5

        if p.args:
            pw += len(p.args)

        if pw > w:
            w = pw

    return w

class ConfigFile:
    def __init__(self, filename):
        self.filename = filename
        self.variables = []

    def add_variable(self, variable):
        self.variables.append(variable)

    def manpage_output(self):
        result = ".SH CONFIGURATION VARIABLES\n"

        for v in self.variables:
            result += ".TP\n"
            result += v.manpage_output()

        return result

    def plaintext_output(self):
        result = ""

        w = parameter_list_width(self.variables)

        for p in self.variables:
            result += p.plaintext_output(w)

        result = result.rstrip() + "\n"

        return result

class Category:
    def __init__(self, description):
        self.description = description
        self.params = []

    def add_param(self, param):
        self.params.append(param)

    # Plain text output

    def plaintext_output(self):
        result = "=== %s ===\n\n" % self.description

        self.params.sort()

        w = parameter_list_width(self.params)

        for p in self.params:
            if p.should_show():
                result += p.plaintext_output(w)

        result = result.rstrip() + "\n"

        return result

119 120 121 122 123 124 125 126 127 128 129 130 131
    def markdown_output(self):
        result = "## %s\n\n| Parameter | Description |\n| - | - |\n" % self.description

        self.params.sort()

        for p in self.params:
            if p.should_show():
                result += p.markdown_output()

        result = result.rstrip() + "\n"

        return result

132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
    def completion_output(self):
        result = ""

        self.params.sort()

        for p in self.params:
            if p.should_show():
                result += p.completion_output(0)

        result = result.rstrip()

        return result

    def manpage_output(self):
        result = ".SH " + self.description.upper() + "\n"

        self.params.sort()

        for p in self.params:
            if p.should_show():
                result += ".TP\n"
                result += p.manpage_output()

        return result

    def wiki_output(self):
        result = "=== %s ===\n" % self.description

        self.params.sort()

        for p in self.params:
            if p.should_show():
                result += "; " + p.wiki_output() + "\n"

        # Escape special HTML characters

        result = result.replace("&", "&amp;")
        result = result.replace("<", "&lt;")
        result = result.replace(">", "&gt;")

        return result

174 175 176 177 178 179 180 181 182 183
categories = (
    (None,      Category("General options")),
    ("game",    Category("Game start options")),
    ("video",   Category("Display options")),
    ("net",     Category("Networking options")),
    ("mod",     Category("Dehacked and WAD merging")),
    ("demo",    Category("Demo options")),
    ("compat",  Category("Compatibility")),
    ("obscure", Category("Obscure and less-used options")),
)
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277

wikipages = []
config_files = {}

# Show options that are in Vanilla Doom? Or only new options?

show_vanilla_options = True

class Parameter:
    def __lt__(self, other):
        return self.name < other.name

    def __init__(self):
        self.text = ""
        self.name = ""
        self.args = None
        self.platform = None
        self.category = None
        self.vanilla_option = False
        self.games = None

    def should_show(self):
        return not self.vanilla_option or show_vanilla_options

    def add_text(self, text):
        if len(text) <= 0:
            pass
        elif text[0] == "@":
            match = re.match('@(\S+)\s*(.*)', text)

            if not match:
                raise "Malformed option line: %s" % text

            option_type = match.group(1)
            data = match.group(2)
            
            if option_type == "arg":
                self.args = data
            elif option_type == "platform":
                self.platform = data
            elif option_type == "category":
                self.category = data
            elif option_type == "vanilla":
                self.vanilla_option = True
            elif option_type == "game":
                self.games = re.split(r'\s+', data.strip())
            else:
                raise "Unknown option type '%s'" % option_type

        else:
            self.text += text + " "

    def _games_only_text(self, pattern="(%s only)"):
        if not match_game and self.games:
            games_list = ", ".join(map(str.capitalize, self.games))
            return " " + (pattern % games_list)
        else:
            return ""

    def manpage_output(self):
        result = self.name

        if self.args:
            result += " " + self.args

        result = '\\fB' + result + '\\fR'

        result += "\n"

        if self.platform:
            result += "[%s only] " % self.platform

        escaped = re.sub('\\\\', '\\\\\\\\', self.text)

        result += escaped + self._games_only_text() + "\n"

        return result

    def wiki_output(self):
        result = self.name

        if self.args:
            result += " " + self.args

        result += ": "

        result += add_wiki_links(self.text)

        if self.platform:
            result += "'''(%s only)'''" % self.platform
        result += self._games_only_text("'''(%s only)'''")

        return result

278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299
    def markdown_output(self):
        if self.args:
            name = "%s %s" % (self.name, self.args)
        else:
            name = "%s" % self.name

        name = name.replace("|", "\\|")

        text = self.text
        if self.platform:
            text += " (%s only)" % self.platform

        text = text.replace("|", "\\|")

        result = "| %s | %s |\n" % (name, text)

        # html escape
        result = result.replace("<", "&lt;")
        result = result.replace(">", "&gt;")

        return result

300
    def plaintext_output(self, indent):
301
        # Build the first line, with the argument on
302
        start = "  " + self.name
303
        if self.args:
304
            start += " " + self.args
305 306

        # pad up to the plaintext width
307
        start += " " * (indent - len(start))
308 309 310 311 312 313 314 315 316 317

        # Build the description text
        description = self.text
        if self.platform:
            description += " (%s only)" % self.platform
        description += self._games_only_text()

        # Build the complete text for the argument
        # Split the description into words and add a word at a time
        result = ""
318 319 320 321 322 323 324 325
        words = [word for word in re.split('\s+', description) if word]
        maxlen = TEXT_WRAP_WIDTH - indent
        outlines = [[]]
        for word in words:
            linelen = sum(len(w) + 1 for w in outlines[-1])
            if linelen + len(word) > maxlen:
                outlines.append([])
            outlines[-1].append(word)
326

327
        linesep = "\n" + " " * indent
328

329 330 331
        return (start +
                linesep.join(" ".join(line) for line in outlines) +
                "\n\n")
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357

    def completion_output(self, w):

        result = self.name + " "

        return result

# Read list of wiki pages

def read_wikipages():
    f = io.open("wikipages", encoding='UTF-8')

    try:
        for line in f:
            line = line.rstrip()

            line = re.sub('\#.*$', '', line)

            if not re.match(r'^\s*$', line):
                wikipages.append(line)
    finally:
        f.close()

# Add wiki page links

def add_wiki_links(text):
358 359 360 361 362 363 364
    def replace_name(m):
        linktext = m.group(1)
        if linktext == pagename:
            return '[[%s]]' % pagename
        else:
            return '[[%s|%s]]' % (pagename, linktext)

365
    for pagename in wikipages:
366 367
        text = re.sub(r'\b(%s)\b' % re.escape(pagename), replace_name,
                      text, count=0, flags=re.IGNORECASE)
368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385

    return text

def add_parameter(param, line, config_file):

    # If we're only targeting a particular game, check this is one of
    # the ones we're targeting.

    if match_game and param.games and match_game not in param.games:
        return

    # Is this documenting a command line parameter?

    match = re.search('(M_CheckParm(WithArgs)|M_ParmExists)?\s*\(\s*"(.*?)"',
                      line)

    if match:
        param.name = match.group(3)
386 387
        category = dict(categories)[param.category]
        category.add_param(param)
388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469
        return

    # Documenting a configuration file variable?

    match = re.search('CONFIG_VARIABLE_\S+\s*\(\s*(\S+?)\),', line)

    if match:
        param.name = match.group(1)
        config_file.add_variable(param)
        return

    raise Exception(param.text)

def process_file(filename):

    current_config_file = None

    f = io.open(filename, encoding='UTF-8')

    try:
        param = None
        waiting_for_checkparm = False

        for line in f:
            line = line.rstrip()

            # Ignore empty lines

            if re.match('\s*$', line):
                continue

            # Currently reading a doc comment?

            if param:
                # End of doc comment

                if not re.match('\s*//', line):
                    waiting_for_checkparm = True

                # The first non-empty line after the documentation comment
                # ends must contain the thing being documented.

                if waiting_for_checkparm:
                    add_parameter(param, line, current_config_file)
                    param = None
                else:
                    # More documentation text

                    munged_line = re.sub('\s*\/\/\s*', '', line, 1)
                    munged_line = re.sub('\s*$', '', munged_line)
                    param.add_text(munged_line)

            # Check for start of a doc comment

            if re.search("//!", line):
                match = re.search("@begin_config_file\s*(\S+)", line)

                if match:
                    # Beginning a configuration file
                    tagname = match.group(1)
                    current_config_file = ConfigFile(tagname)
                    config_files[tagname] = current_config_file
                else:
                    # Start of a normal comment
                    param = Parameter()
                    waiting_for_checkparm = False
    finally:
        f.close()

def process_files(path):
    # Process all C source files.

    if os.path.isdir(path):
        files = glob.glob(path + "/*.c")

        for filename in files:
            process_file(filename)
    else:
        # Special case to allow a single file to be specified as a target

        process_file(path)

470
def print_template(template_file, substs, content):
471 472 473 474 475 476 477 478 479
    f = io.open(template_file, encoding='UTF-8')

    try:
        for line in f:
            match = INCLUDE_STATEMENT_RE.search(line)
            if match:
                filename = match.group(1)
                filename = os.path.join(os.path.dirname(template_file),
                                        filename)
480
                print_template(filename, substs, content)
481 482
            else:
                line = line.replace("@content", content)
483 484
                for k,v in substs.items():
                    line = line.replace(k,v)
485 486 487 488
                stdout(line.rstrip().encode('UTF-8') + b'\n')
    finally:
        f.close()

489
def manpage_output(targets, substs, template_file):
490 491 492 493 494 495 496 497

    content = ""

    for t in targets:
        content += t.manpage_output() + "\n"

    content = content.replace("-", "\\-")

498
    print_template(template_file, substs, content)
499

500
def wiki_output(targets, _, template):
501 502 503 504 505
    read_wikipages()

    for t in targets:
        stdout(t.wiki_output().encode('UTF-8') + b'\n')

506 507 508 509 510 511 512 513
def markdown_output(targets, substs, template_file):
    content = ""

    for t in targets:
        content += t.markdown_output() + "\n"

    print_template(template_file, substs, content)

514
def plaintext_output(targets, substs, template_file):
515 516 517 518 519 520

    content = ""

    for t in targets:
        content += t.plaintext_output() + "\n"

521
    print_template(template_file, substs, content)
522

523
def completion_output(targets, substs, template_file):
524 525 526 527 528 529

    content = ""

    for t in targets:
        content += t.completion_output() + "\n"

530
    print_template(template_file, substs, content)
531 532

def usage():
533
    print("Usage: %s [-V] [-c tag] [-g game] -n program_name -s package_name [ -z shortname ] ( -M | -m | -w | -p ) <dir>..." \
534 535 536
            % sys.argv[0])
    print("   -c :  Provide documentation for the specified configuration file")
    print("         (matches the given tag name in the source file)")
537 538 539
    print("   -s :  Package name, e.g. Chocolate Doom (for substitution)")
    print("   -z :  Package short-name, e.g. Chocolate (for substitution)")
    print("   -n :  Program name, e.g. chocolate (for substitution)")
540
    print("   -M :  Markdown output")
541 542 543 544 545 546 547 548 549 550
    print("   -m :  Manpage output")
    print("   -w :  Wikitext output")
    print("   -p :  Plaintext output")
    print("   -b :  Bash-Completion output")
    print("   -V :  Don't show Vanilla Doom options")
    print("   -g :  Only document options for specified game.")
    sys.exit(0)

# Parse command line

551
opts, args = getopt.getopt(sys.argv[1:], "n:s:z:M:m:wp:b:c:g:V")
552 553 554 555 556

output_function = None
template = None
doc_config_file = None
match_game = None
557
substs = {}
558 559

for opt in opts:
560 561 562 563 564 565
    if opt[0] == "-n":
        substs["@PROGRAM_SPREFIX@"] = opt[1]
    if opt[0] == "-s":
        substs["@PACKAGE_NAME@"] = opt[1]
    if opt[0] == "-z":
        substs["@PACKAGE_SHORTNAME@"] = opt[1]
566 567 568
    if opt[0] == "-m":
        output_function = manpage_output
        template = opt[1]
569 570 571
    elif opt[0] == "-M":
        output_function = markdown_output
        template = opt[1]
572 573 574 575 576 577 578 579 580 581 582 583 584 585
    elif opt[0] == "-w":
        output_function = wiki_output
    elif opt[0] == "-p":
        output_function = plaintext_output
        template = opt[1]
    elif opt[0] == "-b":
        output_function = completion_output
        template = opt[1]
    elif opt[0] == "-V":
        show_vanilla_options = False
    elif opt[0] == "-c":
        doc_config_file = opt[1]
    elif opt[0] == "-g":
        match_game = opt[1]
586 587 588 589 590 591
        substs["@GAME@"] = opt[1]
        substs["@GAME_UPPER@"] = opt[1].title()
        if "doom" == opt[1]:
            substs["@CFGFILE@"] = "default.cfg"
        else:
            substs["@CFGFILE@"] = opt[1] + ".cfg"
592 593 594 595 596 597 598 599 600 601 602

if output_function == None or len(args) < 1:
    usage()
else:
    # Process specified files

    for path in args:
        process_files(path)

    # Build a list of things to document
    if doc_config_file:
603
        documentation_targets = [config_files[doc_config_file]]
604
    else:
605
        documentation_targets = [c for _, c in categories]
606 607

    # Generate the output
608
    output_function(documentation_targets, substs, template)
609