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 sourcedir = sys.argv[1]
  97 targetdir = sys.argv[2]
  98
  99 print "gendoc sourcedir " + sourcedir + " targetdir " + targetdir
 100
 101 if not os.path.exists(targetdir):
 102     os.mkdir(targetdir)
 103
 104 for root, dirs, files in os.walk(sourcedir):
 105     for filename in files:
 106         if len(filename) > 2 and filename[-2:] == ".c":
 107             parsedoc(os.path.join(root, filename), targetdir)
 108     if '.svn' in dirs:
 109         dirs.remove('.svn')