diff --git a/CHANGELOG.md b/CHANGELOG.md index d6c10ae..8d43f42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [2.2.0] +### Added + +- OutputGroup support in the `doxygen` rule [#20](https://github.com/TendTo/rules_doxygen/pull/20) (thanks to @kaycebasques) + ### Changed - Updated documentation diff --git a/docs/doxygen_doc.md b/docs/doxygen_doc.md index 92e128d..9a0c76c 100755 --- a/docs/doxygen_doc.md +++ b/docs/doxygen_doc.md @@ -17,51 +17,51 @@ doxygen(name, srcs, qt_autobrief, multiline_cpp_is_brief, python_docstring, inherit_docs, separate_member_pages, tab_size, aliases, optimize_output_for_c, optimize_output_java, optimize_for_fortran, optimize_output_vhdl, optimize_output_slice, extension_mapping, markdown_support, - toc_include_headings, markdown_id_style, autolink_support, builtin_stl_support, - cpp_cli_support, sip_support, idl_property_support, distribute_group_doc, + toc_include_headings, markdown_id_style, autolink_support, autolink_ignore_words, + builtin_stl_support, cpp_cli_support, sip_support, idl_property_support, distribute_group_doc, group_nested_compounds, subgrouping, inline_grouped_classes, inline_simple_structs, typedef_hides_struct, lookup_cache_size, num_proc_threads, timestamp, extract_all, extract_private, extract_priv_virtual, extract_package, extract_static, extract_local_classes, extract_local_methods, extract_anon_nspaces, resolve_unnamed_params, hide_undoc_members, - hide_undoc_classes, hide_friend_compounds, hide_in_body_docs, internal_docs, case_sense_names, - hide_scope_names, hide_compound_reference, show_headerfile, show_include_files, - show_grouped_memb_inc, force_local_includes, inline_info, sort_member_docs, sort_brief_docs, - sort_members_ctors_1st, sort_group_names, sort_by_scope_name, strict_proto_matching, - generate_todolist, generate_testlist, generate_buglist, generate_deprecatedlist, - enabled_sections, max_initializer_lines, show_used_files, show_files, show_namespaces, - file_version_filter, layout_file, cite_bib_files, external_tool_path, quiet, warnings, - warn_if_undocumented, warn_if_doc_error, warn_if_incomplete_doc, warn_no_paramdoc, - warn_if_undoc_enum_val, warn_as_error, warn_format, warn_line_format, warn_logfile, input, - input_encoding, input_file_encoding, file_patterns, recursive, exclude, exclude_symlinks, - exclude_patterns, exclude_symbols, example_path, example_patterns, example_recursive, - image_path, input_filter, filter_patterns, filter_source_files, filter_source_patterns, - use_mdfile_as_mainpage, fortran_comment_after, source_browser, inline_sources, - strip_code_comments, referenced_by_relation, references_relation, references_link_source, - source_tooltips, use_htags, verbatim_headers, clang_assisted_parsing, clang_add_inc_paths, - clang_options, clang_database_path, alphabetical_index, ignore_prefix, generate_html, - html_output, html_file_extension, html_header, html_footer, html_stylesheet, - html_extra_stylesheet, html_extra_files, html_colorstyle, html_colorstyle_hue, - html_colorstyle_sat, html_colorstyle_gamma, html_dynamic_menus, html_dynamic_sections, - html_code_folding, html_copy_clipboard, html_project_cookie, html_index_num_entries, - generate_docset, docset_feedname, docset_feedurl, docset_bundle_id, docset_publisher_id, - docset_publisher_name, generate_htmlhelp, chm_file, hhc_location, generate_chi, - chm_index_encoding, binary_toc, toc_expand, sitemap_url, generate_qhp, qch_file, - qhp_namespace, qhp_virtual_folder, qhp_cust_filter_name, qhp_cust_filter_attrs, - qhp_sect_filter_attrs, qhg_location, generate_eclipsehelp, eclipse_doc_id, disable_index, - generate_treeview, full_sidebar, enum_values_per_line, show_enum_values, treeview_width, - ext_links_in_window, obfuscate_emails, html_formula_format, formula_fontsize, - formula_macrofile, use_mathjax, mathjax_version, mathjax_format, mathjax_relpath, - mathjax_extensions, mathjax_codefile, searchengine, server_based_search, external_search, - searchengine_url, searchdata_file, external_search_id, extra_search_mappings, generate_latex, - latex_output, latex_cmd_name, makeindex_cmd_name, latex_makeindex_cmd, compact_latex, - paper_type, extra_packages, latex_header, latex_footer, latex_extra_stylesheet, - latex_extra_files, pdf_hyperlinks, use_pdflatex, latex_batchmode, latex_hide_indices, - latex_bib_style, latex_emoji_directory, generate_rtf, rtf_output, compact_rtf, rtf_hyperlinks, - rtf_stylesheet_file, rtf_extensions_file, rtf_extra_files, generate_man, man_output, - man_extension, man_subdir, man_links, generate_xml, xml_output, xml_programlisting, - xml_ns_memb_file_scope, generate_docbook, docbook_output, generate_autogen_def, - generate_sqlite3, sqlite3_output, sqlite3_recreate_db, generate_perlmod, perlmod_latex, - perlmod_pretty, perlmod_makevar_prefix, enable_preprocessing, macro_expansion, + hide_undoc_classes, hide_undoc_namespaces, hide_friend_compounds, hide_in_body_docs, + internal_docs, case_sense_names, hide_scope_names, hide_compound_reference, show_headerfile, + show_include_files, show_grouped_memb_inc, force_local_includes, inline_info, + sort_member_docs, sort_brief_docs, sort_members_ctors_1st, sort_group_names, + sort_by_scope_name, strict_proto_matching, generate_todolist, generate_testlist, + generate_buglist, generate_deprecatedlist, enabled_sections, max_initializer_lines, + show_used_files, show_files, show_namespaces, file_version_filter, layout_file, + cite_bib_files, external_tool_path, quiet, warnings, warn_if_undocumented, warn_if_doc_error, + warn_if_incomplete_doc, warn_no_paramdoc, warn_if_undoc_enum_val, warn_layout_file, + warn_as_error, warn_format, warn_line_format, warn_logfile, input, input_encoding, + input_file_encoding, file_patterns, recursive, exclude, exclude_symlinks, exclude_patterns, + exclude_symbols, example_path, example_patterns, example_recursive, image_path, input_filter, + filter_patterns, filter_source_files, filter_source_patterns, use_mdfile_as_mainpage, + implicit_dir_docs, fortran_comment_after, source_browser, inline_sources, strip_code_comments, + referenced_by_relation, references_relation, references_link_source, source_tooltips, + use_htags, verbatim_headers, clang_assisted_parsing, clang_add_inc_paths, clang_options, + clang_database_path, alphabetical_index, ignore_prefix, generate_html, html_output, + html_file_extension, html_header, html_footer, html_stylesheet, html_extra_stylesheet, + html_extra_files, html_colorstyle, html_colorstyle_hue, html_colorstyle_sat, + html_colorstyle_gamma, html_dynamic_menus, html_dynamic_sections, html_code_folding, + html_copy_clipboard, html_project_cookie, html_index_num_entries, generate_docset, + docset_feedname, docset_feedurl, docset_bundle_id, docset_publisher_id, docset_publisher_name, + generate_htmlhelp, chm_file, hhc_location, generate_chi, chm_index_encoding, binary_toc, + toc_expand, sitemap_url, generate_qhp, qch_file, qhp_namespace, qhp_virtual_folder, + qhp_cust_filter_name, qhp_cust_filter_attrs, qhp_sect_filter_attrs, qhg_location, + generate_eclipsehelp, eclipse_doc_id, disable_index, generate_treeview, full_sidebar, + enum_values_per_line, show_enum_values, treeview_width, ext_links_in_window, obfuscate_emails, + html_formula_format, formula_fontsize, formula_macrofile, use_mathjax, mathjax_version, + mathjax_format, mathjax_relpath, mathjax_extensions, mathjax_codefile, searchengine, + server_based_search, external_search, searchengine_url, searchdata_file, external_search_id, + extra_search_mappings, generate_latex, latex_output, latex_cmd_name, makeindex_cmd_name, + latex_makeindex_cmd, compact_latex, paper_type, extra_packages, latex_header, latex_footer, + latex_extra_stylesheet, latex_extra_files, pdf_hyperlinks, use_pdflatex, latex_batchmode, + latex_hide_indices, latex_bib_style, latex_emoji_directory, generate_rtf, rtf_output, + compact_rtf, rtf_hyperlinks, rtf_stylesheet_file, rtf_extensions_file, rtf_extra_files, + generate_man, man_output, man_extension, man_subdir, man_links, generate_xml, xml_output, + xml_programlisting, xml_ns_memb_file_scope, generate_docbook, docbook_output, + generate_autogen_def, generate_sqlite3, sqlite3_output, sqlite3_recreate_db, generate_perlmod, + perlmod_latex, perlmod_pretty, perlmod_makevar_prefix, enable_preprocessing, macro_expansion, expand_only_predef, search_includes, include_path, include_file_patterns, predefined, expand_as_defined, skip_function_macros, tagfiles, generate_tagfile, allexternals, external_groups, external_pages, hide_undoc_relations, have_dot, dot_num_threads, @@ -70,8 +70,9 @@ doxygen(name, srcs, dot_wrap_threshold, template_relations, include_graph, included_by_graph, call_graph, caller_graph, graphical_hierarchy, directory_graph, dir_graph_max_depth, dot_image_format, interactive_svg, dot_path, dotfile_dirs, dia_path, diafile_dirs, plantuml_jar_path, - plantuml_cfg_file, plantuml_include_path, dot_graph_max_nodes, max_dot_graph_depth, - dot_multi_targets, generate_legend, dot_cleanup, mscgen_tool, mscfile_dirs, **kwargs) + plantuml_cfg_file, plantuml_include_path, plantumlfile_dirs, dot_graph_max_nodes, + max_dot_graph_depth, dot_multi_targets, generate_legend, dot_cleanup, mscgen_tool, + mscfile_dirs, **kwargs) Generates documentation using Doxygen. @@ -125,7 +126,7 @@ doxygen( | configurations | A list of additional configuration parameters to pass to Doxygen. | `None` | | doxyfile_template | The template file to use to generate the Doxyfile. The following substitutions are available:
- `# {{INPUT}}`: Subpackage directory in the sandbox.
- `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.
- `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute. | `None` | | doxygen_extra_args | Extra arguments to pass to the doxygen executable. | `[]` | -| outs | The output folders bazel will keep. If only the html outputs is of interest, the default value will do. otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]). | `["html"]` | +| outs | The output folders bazel will keep. If only the html outputs is of interest, the default value will do. otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]). Note that the rule will also generate an output group for each folder in the outs list having the same name. | `["html"]` | | doxyfile_encoding | This tag specifies the encoding used for all characters in the configuration file that follow. | `None` | | project_name | The `project_name` tag is a single word (or a sequence of words surrounded by double-quotes, unless you are using Doxywizard) that should identify the project for which the documentation is generated. | `None` | | project_number | The `project_number` tag can be used to enter a project or revision number. | `None` | @@ -164,6 +165,7 @@ doxygen( | toc_include_headings | When the `toc_include_headings` tag is set to a non-zero value, all headings up to that level are automatically included in the table of contents, even if they do not have an id attribute. | `None` | | markdown_id_style | The `markdown_id_style` tag can be used to specify the algorithm used to generate identifiers for the Markdown headings. | `None` | | autolink_support | When enabled Doxygen tries to link words that correspond to documented classes, or namespaces to their corresponding documentation. | `None` | +| autolink_ignore_words | This tag specifies a list of words that, when matching the start of a word in the documentation, will suppress auto links generation, if it is enabled via autolink_support. | `None` | | builtin_stl_support | If you use STL classes (i.e. std::string, std::vector, etc.) but do not want to include (a tag file for) the STL sources as input, then you should set this tag to `True` in order to let Doxygen match functions declarations and definitions whose arguments contain STL classes (e.g. func(std::string); versus func(std::string) {}). | `None` | | cpp_cli_support | If you use Microsoft's C++/CLI language, you should set this option to `True` to enable parsing support. | `None` | | sip_support | Set the `sip_support` tag to `True` if your project consists of sip (see: https://www.riverbankcomputing.com/software) sources only. | `None` | @@ -188,6 +190,7 @@ doxygen( | resolve_unnamed_params | If this flag is set to `True`, the name of an unnamed parameter in a declaration will be determined by the corresponding definition. | `None` | | hide_undoc_members | If the `hide_undoc_members` tag is set to `True`, Doxygen will hide all undocumented members inside documented classes or files. | `None` | | hide_undoc_classes | If the `hide_undoc_classes` tag is set to `True`, Doxygen will hide all undocumented classes that are normally visible in the class hierarchy. | `None` | +| hide_undoc_namespaces | If the hide_undoc_namespaces tag is set to YES, Doxygen will hide all undocumented namespaces that are normally visible in the namespace hierarchy. | `None` | | hide_friend_compounds | If the `hide_friend_compounds` tag is set to `True`, Doxygen will hide all friend declarations. | `None` | | hide_in_body_docs | If the `hide_in_body_docs` tag is set to `True`, Doxygen will hide any documentation blocks found inside the body of a function. | `None` | | internal_docs | The `internal_docs` tag determines if documentation that is typed after a \internal command is included. | `None` | @@ -225,6 +228,7 @@ doxygen( | warn_if_incomplete_doc | If `warn_if_incomplete_doc` is set to `True`, Doxygen will warn about incomplete function parameter documentation. | `None` | | warn_no_paramdoc | This `warn_no_paramdoc` option can be enabled to get warnings for functions that are documented, but have no documentation for their parameters or return value. | `None` | | warn_if_undoc_enum_val | If `warn_if_undoc_enum_val` option is set to `True`, Doxygen will warn about undocumented enumeration values. | `None` | +| warn_layout_file | If warn_layout_file option is set to `True`, Doxygen will warn about issues found while parsing the user defined layout file, such as missing or wrong elements | `None` | | warn_as_error | If the `warn_as_error` tag is set to `True` then Doxygen will immediately stop when a warning is encountered. | `None` | | warn_format | The `warn_format` tag determines the format of the warning messages that Doxygen can produce. | `None` | | warn_line_format | In the $text part of the `warn_format` command it is possible that a reference to a more specific place is given. | `None` | @@ -247,6 +251,7 @@ doxygen( | filter_source_files | If the `filter_source_files` tag is set to `True`, the input filter (if set using `input_filter`) will also be used to filter the input files that are used for producing the source files to browse (i.e. when `source_browser` is set to `True`). | `None` | | filter_source_patterns | The `filter_source_patterns` tag can be used to specify source filters per file pattern. | `None` | | use_mdfile_as_mainpage | If the `use_mdfile_as_mainpage` tag refers to the name of a markdown file that is part of the input, its contents will be placed on the main page (index.html). | `None` | +| implicit_dir_docs | If the implicit_dir_docs tag is set to `True`, any README.md file found in subdirectories of the project's root, is used as the documentation for that subdirectory, except when the README.md starts with a \dir, \page or \mainpage command. | `None` | | fortran_comment_after | The Fortran standard specifies that for fixed formatted Fortran code all characters from position 72 are to be considered as comment. | `None` | | source_browser | If the `source_browser` tag is set to `True` then a list of source files will be generated. | `None` | | inline_sources | Setting the `inline_sources` tag to `True` will include the body of functions, multi-line macros, enums or list initialized variables directly into the documentation. | `None` | @@ -419,6 +424,7 @@ doxygen( | plantuml_jar_path | When using PlantUML, the `plantuml_jar_path` tag should be used to specify the path where java can find the plantuml.jar file or to the filename of jar file to be used. | `None` | | plantuml_cfg_file | When using PlantUML, the `plantuml_cfg_file` tag can be used to specify a configuration file for PlantUML. | `None` | | plantuml_include_path | When using PlantUML, the specified paths are searched for files specified by the !include statement in a PlantUML block. | `None` | +| plantumlfile_dirs | The plantumlfile_dirs tag can be used to specify one or more directories that contain PlantUml files that are included in the documentation (see the \plantumlfile command). | `None` | | dot_graph_max_nodes | The `dot_graph_max_nodes` tag can be used to set the maximum number of nodes that will be shown in the graph. | `None` | | max_dot_graph_depth | The `max_dot_graph_depth` tag can be used to set the maximum depth of the graphs generated by dot. | `None` | | dot_multi_targets | Set the `dot_multi_targets` tag to `True` to allow dot to generate multiple output files in one run (i.e. multiple -o and -T options on the command line). | `None` | diff --git a/doxygen/doxygen.bzl b/doxygen/doxygen.bzl index 8ccfb0b..7687776 100644 --- a/doxygen/doxygen.bzl +++ b/doxygen/doxygen.bzl @@ -14,7 +14,14 @@ def _expand_make_variables(string, ctx): def _doxygen_impl(ctx): doxyfile = ctx.actions.declare_file("Doxyfile") - outs = [ctx.actions.declare_directory(out) for out in ctx.attr.outs] + + output_group_info = {} + outs = [] + for out in ctx.attr.outs: + output_dir = ctx.actions.declare_directory(out) + outs += [output_dir] + output_group_info |= {out: depset([output_dir])} + configurations = [_expand_make_variables(conf, ctx) for conf in ctx.attr.configurations] if len(outs) == 0: @@ -39,7 +46,11 @@ def _doxygen_impl(ctx): progress_message = "Running doxygen", executable = ctx.executable._executable, ) - return [DefaultInfo(files = depset(outs))] + + return [ + DefaultInfo(files = depset(outs)), + OutputGroupInfo(**output_group_info), + ] _doxygen = rule( doc = """Run the doxygen binary to generate the documentation. @@ -483,6 +494,7 @@ def doxygen( doxygen_extra_args: Extra arguments to pass to the doxygen executable. outs: The output folders bazel will keep. If only the html outputs is of interest, the default value will do. otherwise, a list of folders to keep is expected (e.g. ["html", "latex"]). + Note that the rule will also generate an output group for each folder in the outs list having the same name. doxyfile_encoding: This tag specifies the encoding used for all characters in the configuration file that follow. project_name: The `project_name` tag is a single word (or a sequence of words surrounded by double-quotes, unless you are using Doxywizard) that should identify the project for which the documentation is generated.