diff --git a/doc/.gitignore b/doc/.gitignore index 2b4b76d19..ae11ebb97 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,8 +1,11 @@ -html/ -html-warn/ +/docset/ +/html/ +/html-warn/ +/ns-3.docset latex/ ns3-object.txt introspected-doxygen.h +doxygen.docset.conf doxygen.log doxygen.warnings.log */build/ diff --git a/doc/ns3_html_theme/static/ns-3-bars-16x16.png b/doc/ns3_html_theme/static/ns-3-bars-16x16.png new file mode 100644 index 000000000..bd36c1cbb Binary files /dev/null and b/doc/ns3_html_theme/static/ns-3-bars-16x16.png differ diff --git a/doc/ns3_html_theme/static/ns-3-bars-32x32.png b/doc/ns3_html_theme/static/ns-3-bars-32x32.png new file mode 100644 index 000000000..20e68120f Binary files /dev/null and b/doc/ns3_html_theme/static/ns-3-bars-32x32.png differ diff --git a/wscript b/wscript index 40e76a4a9..407a05391 100644 --- a/wscript +++ b/wscript @@ -242,6 +242,10 @@ def options(opt): 'but do not wait for ns-3 to finish the full build.'), action="store_true", default=False, dest='doxygen_no_build') + opt.add_option('--docset', + help=('Create Docset, without building. This requires the docsetutil tool from Xcode 9.2 or earlier. See Bugzilla 2196 for more details.'), + action="store_true", default=False, + dest="docset_build") opt.add_option('--enable-des-metrics', help=('Log all events in a json file with the name of the executable (which must call CommandLine::Parse(argc, argv)'), action="store_true", default=False, @@ -1057,6 +1061,10 @@ def build(bld): _doxygen(bld) raise SystemExit(0) + if Options.options.docset_build: + _docset(bld) + raise SystemExit(0) + if Options.options.run_no_build: # Check that the requested program name is valid program_name, dummy_program_argv = wutils.get_run_program(Options.options.run_no_build, wutils.get_command_template(bld.env)) @@ -1266,6 +1274,65 @@ def _doxygen(bld): Logs.error("Doxygen build returned an error.") raise SystemExit(1) +def _docset(bld): + # Get the doxygen config + doxyfile = os.path.join('doc', 'doxygen.conf') + Logs.info("docset: reading " + doxyfile) + doxygen_config = open(doxyfile, 'r') + doxygen_config_contents = doxygen_config.read() + doxygen_config.close() + + # Create the output directory + docset_path = os.path.join('doc', 'docset') + Logs.info("docset: checking for output directory " + docset_path) + if not os.path.exists(docset_path): + Logs.info("docset: creating output directory " + docset_path) + os.mkdir(docset_path) + + doxyfile = os.path.join('doc', 'doxygen.docset.conf') + doxygen_config = open(doxyfile, 'w') + Logs.info("docset: writing doxygen conf " + doxyfile) + doxygen_config.write(doxygen_config_contents) + doxygen_config.write( + """ + HAVE_DOT = NO + GENERATE_DOCSET = YES + DISABLE_INDEX = YES + SEARCHENGINE = NO + GENERATE_TREEVIEW = NO + OUTPUT_DIRECTORY=""" + docset_path + "\n" + ) + doxygen_config.close() + + # Run Doxygen manually, so as to avoid build + Logs.info("docset: running doxygen") + env = wutils.bld.env + _getVersion() + if subprocess.Popen(env['DOXYGEN'] + [doxyfile]).wait(): + Logs.error("Doxygen docset build returned an error.") + raise SystemExit(1) + + # Build docset + docset_path = os.path.join(docset_path, 'html') + Logs.info("docset: Running docset Make") + if subprocess.Popen(["make"], cwd=docset_path).wait(): + Logs.error("Docset make returned and error.") + raise SystemExit(1) + + # Additional steps from + # https://github.com/Kapeli/Dash-User-Contributions/tree/master/docsets/ns-3 + docset_out = os.path.join(docset_path, 'org.nsnam.ns3.docset') + icons = os.path.join('doc', 'ns3_html_theme', 'static') + shutil.copy(os.path.join(icons, 'ns-3-bars-16x16.png'), + os.path.join(docset_out, 'icon.png')) + shutil.copy(os.path.join(icons, 'ns-3-bars-32x32.png'), + os.path.join(docset_out, 'icon@x2.png')) + shutil.copy(os.path.join(docset_path, 'Info.plist'), + os.path.join(docset_out, 'Contents')) + shutil.move(docset_out, os.path.join('doc', 'ns-3.docset')) + + print("Docset built successfully.") + def _getVersion(): """update the ns3_version.js file, when building documentation"""