workbench/locale/help/gendoc.py

   1 # -*- coding: iso-8859-1 -*-
   2 # Copyright (C) 2013, The AROS Development Team. All rights reserved.
   3 # $Id$
   4
   5 """Documentation to guide.
   6
   7 Extract documentation from C source files and create guide files
   8
   9 Usage: python gendoc.py <sourcedir> <targetdir>
  10
  11 <sourcedir> will be scanned recursively for C source files.
  12 <targetdir> where to place the guide. Directory will be created
  13             if it doesn't exist.
  14 """
  15
  16 import re
  17 import os
  18 import sys
  19 import datetime
  20
  21 # Regex for whole autodoc block (without surrounding comments)
  22 AD_REGX = re.compile(r"""
  23 ^/\*{6,}
  24 (
  25 .*?
  26 ^\s{4,4}NAME
  27 .*?
  28 )
  29 ^\*{7,}/
  30 """, re.VERBOSE | re.MULTILINE | re.DOTALL)
  31
  32 # Regex for a title
  33 TITLES_REGX = re.compile(r"""
  34 ^\s{4,4}
  35 (NAME|FORMAT|SYNOPSIS|LOCATION|FUNCTION|INPUTS|TAGS|RESULT|EXAMPLE|NOTES|BUGS|SEE\ ALSO|INTERNALS|HISTORY|TEMPLATE)$
  36 """, re.VERBOSE)
  37
  38
  39 def parsedoc(filename, targetdir):
  40     # print "reading " + filename
  41     blocks = {}
  42     filehandle = open(filename)
  43     content = filehandle.read()
  44     doc = AD_REGX.search(content)
  45     current_title = None
  46     if doc:
  47         for line in doc.group(1).splitlines():
  48             match = TITLES_REGX.match(line)
  49             if match:
  50                 current_title = match.group(1)
  51                 blocks[current_title] = ""
  52             elif current_title:
  53                 blocks[current_title] += line.expandtabs()[4:] + "\n"
  54
  55         # check for empty chapters, because we don't want to print them
  56         for title, content in blocks.iteritems():
  57             if content.strip() == "":
  58                 blocks[title] = ""
  59
  60     filehandle.close()
  61
  62     if blocks.has_key("NAME"):
  63         # get docname
  64         docname = blocks["NAME"].split()[0]
  65         if docname == "":
  66             raise ValueError("docname is empty")
  67
  68         docfilename = docname + ".guide"
  69         today = datetime.date.today()
  70         filehandle = open(os.path.join(targetdir, docfilename), "w")
  71
  72         # The titles we want to printed
  73         shell_titles = ("Name", "Format", "Template", "Synopsis", "Location", "Function",
  74                         "Inputs", "Tags", "Result", "Example", "Notes", "Bugs", "See also")
  75
  76         filehandle.write("@DATABASE %s\n\n" % (docfilename))
  77         filehandle.write("@$VER: %s 1.0 (%d.%d.%d)\n" % (docfilename, today.day, today.month, today.year))
  78         filehandle.write("@(C) Copyright (C) %d, The AROS Development Team. All rights reserved.\n" % (today.year))
  79         filehandle.write("@MASTER %s\n\n" %(filename))
  80         filehandle.write("@NODE MAIN \"%s\"\n\n" % (docname))
  81
  82         for title in shell_titles:
  83             title_key = title.upper()
  84             if blocks.has_key(title_key) and blocks[title_key] != "":
  85                 filehandle.write("@{B}" + title + "@{UB}\n")
  86                 filehandle.write(blocks[title_key])
  87                 filehandle.write("\n")
  88
  89         filehandle.write('@TOC "HELP:English/Index.guide/MAIN"\n')
  90         filehandle.write("@ENDNODE\n")
  91
  92         filehandle.close()
  93
  94 ###############################################################################
  95
  96 def main():
  97     sourcedir = sys.argv[1]
  98     targetdir = sys.argv[2]
  99
 100     print "gendoc sourcedir " + sourcedir + " targetdir " + targetdir
 101
 102     if not os.path.exists(targetdir):
 103         os.mkdir(targetdir)
 104
 105     for root, dirs, files in os.walk(sourcedir):
 106         for filename in files:
 107             if len(filename) > 2 and filename[-2:] == ".c":
 108                 parsedoc(os.path.join(root, filename), targetdir)
 109         if '.svn' in dirs:
 110             dirs.remove('.svn')
 111
 112
 113 if __name__ == "__main__":
 114     main()