VirtualBox

Ignore:
Timestamp:
Mar 20, 2023 12:01:53 PM (2 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
156429
Message:

manual/Makefile.kmk: Cleaning up html and qhelp outputting. The latter doesn't need an extra copy of the Docbook version of the images, since DITA-OT copies the necessary images to qhelp/topics/images/. bugref:10348 bugref:10302

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/htmlhelp-qthelp.py

    r98950 r99064  
    11#!/usr/bin/python3
    2 
     2# -*- coding: utf-8 -*-
    33# $Id$
    4 ## @file
    5 # A python script to create a .qhp file out of a given htmlhelp
    6 # folder. Lots of things about the said folder is assumed. Please
    7 # see the code and inlined comments.
    8 
    9 import sys, getopt
    10 import os.path
    11 import re
    12 import logging
    13 
    14 if sys.version_info >= (3, 0):
    15     from html.parser import HTMLParser
    16 else:
    17     from HTMLParser import HTMLParser
    18 
    19 
     4
     5"""
     6A python script to create a .qhp file out of a given htmlhelp
     7folder. Lots of things about the said folder is assumed. Please
     8see the code and inlined comments.
     9"""
    2010
    2111__copyright__ = \
    … …  
    4232"""
    4333
     34import getopt
     35import logging
     36import os.path
     37import re
     38import sys
     39
     40if sys.version_info[0] >= 3:
     41    from html.parser import HTMLParser
     42else:
     43    from HTMLParser import HTMLParser
     44
    4445# number of opened and not yet closed section tags of toc section
    4546open_section_tags = 0
    … …  
    4748html_files = []
    4849
    49 # use html_parser stuff to collect <a name tags
    5050def create_keywords_section(folder):
     51    """
     52    use html_parser stuff to collect <a name ...> tags
     53    """
    5154    keywords_section_lines = ['<keywords>']
    5255    for html_file_name in html_files:
    … …  
    5558
    5659        class html_parser(HTMLParser):
    57           def __init__(self):
    58             HTMLParser.__init__(self)
    59             self.a_tag=[]
    60           def handle_starttag(self, tag, attributes):
    61             if tag != 'div' and tag != 'a':
    62               return
    63             if tag == 'a':
    64               for a in attributes:
    65                 if a[0] == 'name':
    66                   self.a_tag.append(a[1])
     60            def __init__(self):
     61                HTMLParser.__init__(self)
     62                self.a_tag = []
     63            def handle_starttag(self, tag, attrs):
     64                if tag != 'div' and tag != 'a':
     65                    return
     66                if tag == 'a':
     67                    for a in attrs:
     68                        if a[0] == 'name':
     69                            self.a_tag.append(a[1])
    6770
    6871        parser = html_parser()
    … …  
    7073        for k in parser.a_tag:
    7174            line = '<keyword name="' + k + '" id="' + k + '" ref="' + html_file_name + '#' + k + '"/>'
    72             keywords_section_lines.append(line);
     75            keywords_section_lines.append(line)
    7376    keywords_section_lines.append('</keywords>')
    7477    return keywords_section_lines
    7578
    76 # find the png files under /images folder and create a part of the
    77 # qhelp project file with <file> tags
    7879def create_image_list(folder):
    79     image_folder_name = 'images'
    80     image_files_list = []
    81     # Look for 'images' sub folder
    82     subdirs = [x[0] for x in os.walk(folder)]
    83     full_folder_path = os.path.join(folder, image_folder_name)
    84     if full_folder_path not in subdirs:
    85         logging.error('Image subfolder "%s" is not found under "%s".', image_folder_name, folder)
    86         return image_files_list;
    87     png_files = []
    88     for f in os.listdir(full_folder_path):
    89         png_files.append(image_folder_name + '/' + f)
    90         image_files_list.append('<file>images/' + f + '</file>')
    91     return image_files_list
    92 
    93 # open files list and read the list of html files from there
     80    """
     81    find the png files under topics/images folder and create a part of the
     82    qhelp project file with <file> tags
     83    """
     84    sFullImageFolderPath = os.path.join(folder, 'topics', 'images');
     85    if not os.path.isdir(sFullImageFolderPath):
     86        logging.error('Image subfolder "topics/images" is not found under "%s"!', folder)
     87        sys.exit(1);
     88    return ['<file>topics/images/%s</file>' % sFile for sFile in os.listdir(sFullImageFolderPath)];
     89
    9490def create_html_list(folder, list_file):
     91    """
     92    open files list and read the list of html files from there
     93    """
    9594    global html_files
    9695    html_file_lines = []
    … …  
    9998        return html_file_lines
    10099    full_path = os.path.join(folder, list_file)
    101     file = open(full_path, encoding='utf-8')
    102 
    103     lines = file.readlines()
    104     file.close()
     100    with open(full_path, encoding='utf-8') as file:
     101        lines = file.readlines()
     102
    105103    # first search for the [FILES] marker then collect .html lines
    106104    marker_found = 0
    … …  
    126124def parse_param_tag(line):
    127125    label = 'value="'
    128     start = line.find(label);
     126    start = line.find(label)
    129127    if start == -1:
    130128        return ''
    131     start +=  len(label)
     129    start += len(label)
    132130    end = line.find('"', start)
    133131    if end == -1:
    134         return '';
     132        return ''
    135133    return line[start:end]
    136134
    137 # look at next two lines. they are supposed to look like the following
    138 #      <param name="Name" value="Oracle VM VirtualBox">
    139 #      <param name="Local" value="index.html">
    140 # parse out value fields and return
    141 # title="Oracle VM VirtualBox" ref="index.html
    142135def parse_object_tag(lines, index):
    143     result=''
     136    """
     137    look at next two lines. they are supposed to look like the following
     138         <param name="Name" value="Oracle VM VirtualBox">
     139         <param name="Local" value="index.html">
     140    parse out value fields and return
     141    title="Oracle VM VirtualBox" ref="index.html
     142    """
     143    result = ''
    144144    if index + 2 > len(lines):
    145         logging.warning('Not enough tags after this one "%s"',lines[index])
     145        logging.warning('Not enough tags after this one "%s"', lines[index])
    146146        return result
    147     if not re.match(r'^\s*<param', lines[index + 1], re.IGNORECASE) or \
    148        not re.match(r'^\s*<param', lines[index + 2], re.IGNORECASE):
    149         logging.warning('Skipping the line "%s" since next two tags are supposed to be param tags',  lines[index])
     147    if    not re.match(r'^\s*<param', lines[index + 1], re.IGNORECASE) \
     148       or not re.match(r'^\s*<param', lines[index + 2], re.IGNORECASE):
     149        logging.warning('Skipping the line "%s" since next two tags are supposed to be param tags', lines[index])
    150150        return result
    151151    title = parse_param_tag(lines[index + 1])
    … …  
    159159    return result
    160160
    161 # parse any string other than staring with <OBJECT
    162 # decide if <session tag should be closed
    163161def parse_non_object_tag(lines, index):
     162    """
     163    parse any string other than staring with <OBJECT
     164    decide if <section> tag should be closed
     165    """
     166
    164167    if index + 1 > len(lines):
    165168        return ''
    … …  
    178181
    179182def parse_line(lines, index):
    180     result=''
     183    result = ''
    181184
    182185    # if the line starts with <OBJECT
    … …  
    187190    return result
    188191
    189 # parse TOC file. assuming all the relevant information
    190 # is stored in tags and attributes. whatever is outside of
    191 # <... > pairs is filtered out. we also assume < ..> are not nested
    192 # and each < matches to a >
    193192def create_toc(folder, toc_file):
     193    """
     194    parse TOC file. assuming all the relevant information
     195    is stored in tags and attributes. whatever is outside of
     196    <... > pairs is filtered out. we also assume < ..> are not nested
     197    and each < matches to a >
     198    """
    194199    toc_string_list = []
    195200    content = [x[2] for x in os.walk(folder)]
    … …  
    198203        return toc_string_list
    199204    full_path = os.path.join(folder, toc_file)
    200     file = open(full_path, encoding='utf-8')
    201     content = file.read()
    202     file.close()
     205    with open(full_path, encoding='utf-8') as file:
     206        content = file.read()
     207
    203208    # convert the file string into a list of tags there by eliminating whatever
    204209    # char reside outside of tags.
    … …  
    219224    # lines = content.split('\n')
    220225    toc_string_list.append('<toc>')
    221     index = 0
    222     for tag in tag_list:
     226    for index, _ in enumerate(tag_list):
    223227        str = parse_line(tag_list, index)
    224228        if str:
    225229            toc_string_list.append(str)
    226         index += 1
    227230    toc_string_list.append('</toc>')
    228231    toc_string = '\n'.join(toc_string_list)
    … …  
    230233    return toc_string_list
    231234
    232 def usage(arg):
     235def usage(iExitCode):
    233236    print('htmlhelp-qthelp.py -d <helphtmlfolder> -o <outputfilename>')
    234     sys.exit()
     237    return iExitCode
    235238
    236239def main(argv):
     240    # Parse arguments.
    237241    helphtmlfolder = ''
    238242    output_filename = ''
    … …  
    240244    toc_file = ''
    241245    try:
    242         opts, args = getopt.getopt(sys.argv[1:],"hd:o:f:t:")
     246        opts, _ = getopt.getopt(argv[1:], "hd:o:f:t:")
    243247    except getopt.GetoptError as err:
    244         print(err)
    245         usage(2)
     248        logging.error(str(err))
     249        return usage(2)
    246250    for opt, arg in opts:
    247251        if opt == '-h':
    248             usage(0)
    249         elif opt in ("-d"):
     252            return usage(0)
     253        if opt == "-d":
    250254            helphtmlfolder = arg
    251255            print(helphtmlfolder)
    252         elif opt in ("-f"):
     256        elif opt == "-f":
    253257            list_file = arg
    254         elif opt in ("-t"):
     258        elif opt == "-t":
    255259            toc_file = arg
    256260            print(toc_file)
    257         elif opt in ("-o"):
    258              output_filename = arg
     261        elif opt == "-o":
     262            output_filename = arg
    259263    # check supplied helphtml folder argument
    260264    if not helphtmlfolder:
    261265        logging.error('No helphtml folder is provided. Exiting')
    262         usage(2)
     266        return usage(2)
    263267    if not os.path.exists(helphtmlfolder):
    264268        logging.error('folder "%s" does not exist. Exiting', helphtmlfolder)
    265         usage(2)
     269        return usage(2)
    266270    helphtmlfolder = os.path.normpath(helphtmlfolder)
    267271
    … …  
    269273    if not output_filename:
    270274        logging.error('No filename for output is given. Exiting')
    271         usage(2)
    272 
    273     out_xml_lines = ['<?xml version="1.0" encoding="UTF-8"?>', \
    274                      '<QtHelpProject version="1.0">' , \
    275                      '<namespace>org.virtualbox</namespace>', \
    276                      '<virtualFolder>doc</virtualFolder>', \
     275        return usage(2)
     276
     277    out_xml_lines = ['<?xml version="1.0" encoding="UTF-8"?>',
     278                     '<QtHelpProject version="1.0">',
     279                     '<namespace>org.virtualbox</namespace>',
     280                     '<virtualFolder>doc</virtualFolder>',
    277281                     '<filterSection>']
    278     out_xml_lines += create_toc(helphtmlfolder, toc_file) + create_files_section(helphtmlfolder, list_file)
     282    out_xml_lines += create_toc(helphtmlfolder, toc_file)
     283    out_xml_lines += create_files_section(helphtmlfolder, list_file)
    279284    out_xml_lines += create_keywords_section(helphtmlfolder)
    280285    out_xml_lines += ['</filterSection>', '</QtHelpProject>']
    281286
    282     out_file = open(output_filename, 'wb')
    283     out_file.write('\n'.join(out_xml_lines).encode('utf8'))
    284     out_file.close()
     287    with open(output_filename, 'wb') as out_file:
     288        out_file.write('\n'.join(out_xml_lines).encode('utf8'))
     289    return 0
    285290
    286291if __name__ == '__main__':
    287     main(sys.argv[1:])
     292    sys.exit(main(sys.argv))
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette