File indexing completed on 2024-03-24 03:55:14
0001 # -*- coding: utf-8 -*- 0002 # 0003 # SPDX-FileCopyrightText: 2014 Aurélien Gâteau <agateau@kde.org> 0004 # 0005 # SPDX-License-Identifier: BSD-2-Clause 0006 0007 import argparse 0008 import logging 0009 import os 0010 import sys 0011 0012 0013 def normalized_path(inputpath): 0014 return os.path.normpath(inputpath) 0015 0016 0017 def parse_args(depdiagram_available): 0018 import textwrap 0019 parser = argparse.ArgumentParser( 0020 formatter_class=argparse.RawDescriptionHelpFormatter, 0021 description=textwrap.dedent('''Generate API documentation of complex projects. 0022 0023 >> This function must be run from an empty directory (where the documentation will be built).''') 0024 ) 0025 group = add_sources_group(parser) 0026 group.add_argument('sourcesdir', type=normalized_path, 0027 help='Location of the sources.') 0028 group.add_argument('--depdiagram-dot-dir', type=normalized_path, 0029 help='Generate dependency diagrams, using the .dot files from DIR.', 0030 metavar="DIR") 0031 add_output_group(parser) 0032 add_qt_doc_group(parser) 0033 add_paths_group(parser) 0034 add_misc_group(parser) 0035 args = parser.parse_args() 0036 check_common_args(args) 0037 0038 if args.depdiagram_dot_dir and not depdiagram_available: 0039 logging.error('You need to install the Graphviz Python bindings to ' 0040 'generate dependency diagrams.\n' 0041 'See <https://www.graphviz.org/download/>.') 0042 exit(1) 0043 0044 if not os.path.isdir(args.sourcesdir): 0045 logging.error(args.sourcesdir + " is not a directory") 0046 exit(2) 0047 0048 return args 0049 0050 0051 def add_sources_group(parser): 0052 group = parser.add_argument_group('sources') 0053 group.add_argument('--accountsfile', type=normalized_path, 0054 help='File with accounts information of SVN contributors.') 0055 return group 0056 0057 0058 def add_output_group(parser): 0059 group = parser.add_argument_group('output options') 0060 group.add_argument('--title', default='API Documentation', 0061 help='String to use for page titles.') 0062 group.add_argument('--man-pages', action='store_true', 0063 help='Generate man page documentation.') 0064 group.add_argument('--qhp', action='store_true', 0065 help='Generate Qt Compressed Help documentation.') 0066 return group 0067 0068 0069 def add_qt_doc_group(parser): 0070 group = parser.add_argument_group('Qt documentation') 0071 group.add_argument('--qtdoc-dir', type=normalized_path, 0072 help='Location of (local) Qt documentation; this is searched ' + 0073 'for tag files to create links to Qt classes.') 0074 group.add_argument('--qtdoc-link', 0075 help='Override Qt documentation location for the links in the ' + 0076 'html files. May be a path or URL.') 0077 group.add_argument('--qtdoc-flatten-links', action='store_true', 0078 help='Whether to assume all Qt documentation html files ' + 0079 'are immediately under QTDOC_LINK (useful if you set ' + 0080 'QTDOC_LINK to the online Qt documentation). Ignored ' + 0081 'if QTDOC_LINK is not set.') 0082 return group 0083 0084 0085 def add_paths_group(parser): 0086 group = parser.add_argument_group('paths') 0087 group.add_argument('--doxygen', default='doxygen', type=normalized_path, 0088 help='(Path to) the doxygen executable.') 0089 group.add_argument('--qhelpgenerator', default='qhelpgenerator', type=normalized_path, 0090 help='(Path to) the qhelpgenerator executable.') 0091 return group 0092 0093 0094 def add_misc_group(parser): 0095 scriptdir = os.path.dirname(os.path.realpath(__file__)) 0096 doxdatadir = os.path.join(scriptdir, 'data') 0097 0098 group = parser.add_argument_group('misc') 0099 group.add_argument('--doxdatadir', default=doxdatadir, type=normalized_path, 0100 help='Location of the HTML header files and support graphics.') 0101 group.add_argument('--keep-temp-dirs', action='store_true', 0102 help='Do not delete temporary dirs, useful for debugging.') 0103 return parser 0104 0105 0106 def check_common_args(args): 0107 if not _is_doxdatadir(args.doxdatadir): 0108 logging.error(f'{args.doxdatadir} is not a valid doxdatadir') 0109 sys.exit(1) 0110 0111 0112 def _is_doxdatadir(directory): 0113 for name in ['header.html', 'footer.html', 'htmlresource']: 0114 if not os.path.exists(os.path.join(directory, name)): 0115 return False 0116 return True