1# -*- coding: utf-8 -*- 2# 3# SPDX-FileCopyrightText: 2014 Aurélien Gâteau <agateau@kde.org> 4# 5# SPDX-License-Identifier: BSD-2-Clause 6 7import argparse 8import logging 9import os 10import sys 11 12 13def normalized_path(inputpath): 14 return os.path.normpath(inputpath) 15 16def parse_args(depdiagram_available): 17 import textwrap 18 parser = argparse.ArgumentParser( 19 formatter_class=argparse.RawDescriptionHelpFormatter, 20 description=textwrap.dedent('''Generate API documentation of complex projects. 21 22>> This function must be run from an empty directory (where the documentation will be built).''') 23 ) 24 group = add_sources_group(parser) 25 group.add_argument('sourcesdir', type=normalized_path, 26 help='Location of the sources.') 27 group.add_argument('--depdiagram-dot-dir', type=normalized_path, 28 help='Generate dependency diagrams, using the .dot files from DIR.', 29 metavar="DIR") 30 add_output_group(parser) 31 add_qt_doc_group(parser) 32 add_paths_group(parser) 33 add_misc_group(parser) 34 args = parser.parse_args() 35 check_common_args(args) 36 37 if args.depdiagram_dot_dir and not depdiagram_available: 38 logging.error('You need to install the Graphviz Python bindings to ' 39 'generate dependency diagrams.\n' 40 'See <https://www.graphviz.org/download/>.') 41 exit(1) 42 43 if not os.path.isdir(args.sourcesdir): 44 logging.error(args.sourcesdir + " is not a directory") 45 exit(2) 46 47 return args 48 49 50def add_sources_group(parser): 51 group = parser.add_argument_group('sources') 52 group.add_argument('--accountsfile', type=normalized_path, 53 help='File with accounts information of SVN contributors.') 54 return group 55 56def add_output_group(parser): 57 group = parser.add_argument_group('output options') 58 group.add_argument('--title', default='API Documentation', 59 help='String to use for page titles.') 60 group.add_argument('--man-pages', action='store_true', 61 help='Generate man page documentation.') 62 group.add_argument('--qhp', action='store_true', 63 help='Generate Qt Compressed Help documentation.') 64 return group 65 66 67def add_qt_doc_group(parser): 68 group = parser.add_argument_group('Qt documentation') 69 group.add_argument('--qtdoc-dir', type=normalized_path, 70 help='Location of (local) Qt documentation; this is searched ' + 71 'for tag files to create links to Qt classes.') 72 group.add_argument('--qtdoc-link', 73 help='Override Qt documentation location for the links in the ' + 74 'html files. May be a path or URL.') 75 group.add_argument('--qtdoc-flatten-links', action='store_true', 76 help='Whether to assume all Qt documentation html files ' + 77 'are immediately under QTDOC_LINK (useful if you set ' + 78 'QTDOC_LINK to the online Qt documentation). Ignored ' + 79 'if QTDOC_LINK is not set.') 80 return group 81 82 83def add_paths_group(parser): 84 group = parser.add_argument_group('paths') 85 group.add_argument('--doxygen', default='doxygen', type=normalized_path, 86 help='(Path to) the doxygen executable.') 87 group.add_argument('--qhelpgenerator', default='qhelpgenerator', type=normalized_path, 88 help='(Path to) the qhelpgenerator executable.') 89 return group 90 91 92def add_misc_group(parser): 93 scriptdir = os.path.dirname(os.path.realpath(__file__)) 94 doxdatadir = os.path.join(scriptdir, 'data') 95 96 group = parser.add_argument_group('misc') 97 group.add_argument('--doxdatadir', default=doxdatadir, type=normalized_path, 98 help='Location of the HTML header files and support graphics.') 99 group.add_argument('--keep-temp-dirs', action='store_true', 100 help='Do not delete temporary dirs, useful for debugging.') 101 return parser 102 103 104def check_common_args(args): 105 if not _is_doxdatadir(args.doxdatadir): 106 logging.error("{} is not a valid doxdatadir".format(args.doxdatadir)) 107 sys.exit(1) 108 109 110def _is_doxdatadir(directory): 111 for name in ['header.html', 'footer.html', 'htmlresource']: 112 if not os.path.exists(os.path.join(directory, name)): 113 return False 114 return True 115