feat: collect transitive sources

.bcr/presubmit.yml

@@ -17,3 +17,4 @@ bcr_test_module:
         - "//awesome:doxygen"
         - "//kwargs:doxygen"
         - "//substitutions:doxygen"
+        - "//dependencies:doxygen"

.github/workflows/ci.yml

@@ -25,6 +25,7 @@ jobs:
             custom,
             awesome,
             substitutions,
+            dependencies,
           ]
         exclude:
           # In substitution example we use `string_keyed_label_dict`, which is not supported in bazel 7.0.0
@@ -54,17 +55,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        subdir:
-          [
-            base,
-            kwargs,
-            doxyfile,
-            latex,
-            nested,
-            custom,
-            awesome,
-            substitutions,
-          ]
+        subdir: [base]
     runs-on: ${{ matrix.os }}
 
     steps:

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.3]
+
+### Added
+
+- Support for dependency inclusion in the `doxygen` rule [#24](https://github.com/TendTo/rules_doxygen/pull/24) (thanks to @oxidase)
+
+### Changed
+
+- `srcs` attribute in the `doxygen` macro is now optional, as it defaults to `[]`
+- Updated documentation
+
 ## [2.2.2]
 
 ### Added
@@ -155,4 +166,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [2.2.0]: https://github.com/TendTo/rules_doxygen/compare/2.1.0...2.2.0
 [2.2.1]: https://github.com/TendTo/rules_doxygen/compare/2.2.0...2.2.1
 [2.2.2]: https://github.com/TendTo/rules_doxygen/compare/2.2.1...2.2.2
-[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/2.2.2...HEAD
+[2.2.3]: https://github.com/TendTo/rules_doxygen/compare/2.2.2...2.2.3
+[NEXT.VERSION]: https://github.com/TendTo/rules_doxygen/compare/2.2.3...HEAD

README.md

@@ -150,6 +150,10 @@ doxygen(
         "*.h",          # Usually includes the source files and the markdown files.
         "*.cpp",
     ]) + ["README.md"],
+    # Additionally, you can use the `deps` attribute to select a target
+    # and automatically include all of the files in its `srcs`, `hdrs`, and `data` attributes,
+    # along with all of its transitive dependencies.
+    # deps = [":my_cc_target"],
     project_brief = DESCRIPTION,            # Brief description of the project
     project_name = NAME,                    # Name of the project
     generate_html = True,                   # Whether to generate HTML output
@@ -173,6 +177,73 @@ They will simply be appended at the end of the file, overriding the default valu
 > [!Note]
 > See the [documentation](docs/doxygen_doc.md) for more information or the [examples](examples) directory for examples of how to use the rules.
 
+### Differences between `srcs` and `deps`
+
+The `srcs` and `deps` attributes work differently, and are not interchangeable.
+
+`srcs` is a list of files that will be passed to Doxygen for documentation generation.
+You can use `glob` to include a collection of multiple files.  
+On the other hand, if you indicate a target (e.g., `:my_genrule`), it will include all the files produced by that target.
+More precisely, the files in the DefaultInfo provider the target returns.
+Hence, when the documentation is generated, all rules in the `srcs` attribute **will** be built, and the files they output will be passed to Doxygen.
+
+On the other hand, `deps` is a list of targets whose sources will be included in the documentation generation.
+It will automatically include all the files in the `srcs`, `hdrs`, and `data` attributes of the target, and the same applies to all of its transitive dependencies, recursively.
+Since we are only interested in the source files, the `deps` targets **will not** be built when the documentation is generated.
+
+```bzl
+# My BUILD.bazel file
+load("@doxygen//:doxygen.bzl", "doxygen")
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+    name = "lib",
+    hdrs = ["add.h", "sub.h"],
+    srcs = ["add.cpp", "sub.cpp"],
+)
+
+cc_library(
+    name = "main",
+    srcs = ["main.cpp"],
+    deps = [":lib"],
+)
+
+
+genrule(
+    name = "section",
+    outs = ["Section.md"],
+    cmd = """
+        echo "# Section " > $@
+        echo "This is some amazing documentation with section!!  " >> $@
+        echo "Incredible." >> $@
+    """,
+)
+
+doxygen(
+    name = "doxygen",
+    project_name = "dependencies",
+
+    # The output of the genrule will be included in the documentation.
+    # The genrule will be executed when the documentation is generated.
+    srcs = [
+        "README.md",  # file
+        ":section",  # genrule
+
+        # WARNING: By adding this, the main target will be built
+        # and only the output file `main.o` will be passed to Doxygen,
+        # which is likely not what you want.
+        # ":main"
+    ],
+
+    # The sources of the main target and its dependencies will be included.
+    # No compilation will be performed, so compile error won't be reported.
+    deps = [":main"],  # cc_library
+
+    # Always starts at the root folder
+    use_mdfile_as_mainpage = "dependencies/README.md",
+)
+```
+
 ## Build
 
 To build the documentation, run the following command:

docs/doxygen_doc.md

@@ -2,29 +2,49 @@
 
 Doxygen rule for Bazel.
 
+<a id="TransitiveSourcesInfo"></a>
+
+## TransitiveSourcesInfo
+
+<pre>
+load("@rules_doxygen//doxygen:doxygen.bzl", "TransitiveSourcesInfo")
+
+TransitiveSourcesInfo(<a href="#TransitiveSourcesInfo-srcs">srcs</a>)
+</pre>
+
+A provider to collect source files transitively from the target and its dependencies
+
+**FIELDS**
+
+| Name  | Description |
+| :------------- | :------------- |
+| <a id="TransitiveSourcesInfo-srcs"></a>srcs |  depset of source files collected from the target and its dependencies    |
+
+
 <a id="doxygen"></a>
 
 ## doxygen
 
 <pre>
 load("@doxygen//:doxygen.bzl", "doxygen")
 
-doxygen(<a href="#doxygen-name">name</a>, <a href="#doxygen-srcs">srcs</a>, <a href="#doxygen-dot_executable">dot_executable</a>, <a href="#doxygen-configurations">configurations</a>, <a href="#doxygen-doxyfile_template">doxyfile_template</a>, <a href="#doxygen-doxygen_extra_args">doxygen_extra_args</a>, <a href="#doxygen-outs">outs</a>,
-        <a href="#doxygen-doxyfile_encoding">doxyfile_encoding</a>, <a href="#doxygen-project_name">project_name</a>, <a href="#doxygen-project_number">project_number</a>, <a href="#doxygen-project_brief">project_brief</a>, <a href="#doxygen-project_logo">project_logo</a>, <a href="#doxygen-project_icon">project_icon</a>,
-        <a href="#doxygen-create_subdirs">create_subdirs</a>, <a href="#doxygen-create_subdirs_level">create_subdirs_level</a>, <a href="#doxygen-allow_unicode_names">allow_unicode_names</a>, <a href="#doxygen-output_language">output_language</a>, <a href="#doxygen-brief_member_desc">brief_member_desc</a>,
-        <a href="#doxygen-repeat_brief">repeat_brief</a>, <a href="#doxygen-abbreviate_brief">abbreviate_brief</a>, <a href="#doxygen-always_detailed_sec">always_detailed_sec</a>, <a href="#doxygen-inline_inherited_memb">inline_inherited_memb</a>, <a href="#doxygen-full_path_names">full_path_names</a>,
-        <a href="#doxygen-strip_from_path">strip_from_path</a>, <a href="#doxygen-strip_from_inc_path">strip_from_inc_path</a>, <a href="#doxygen-short_names">short_names</a>, <a href="#doxygen-javadoc_autobrief">javadoc_autobrief</a>, <a href="#doxygen-javadoc_banner">javadoc_banner</a>,
-        <a href="#doxygen-qt_autobrief">qt_autobrief</a>, <a href="#doxygen-multiline_cpp_is_brief">multiline_cpp_is_brief</a>, <a href="#doxygen-python_docstring">python_docstring</a>, <a href="#doxygen-inherit_docs">inherit_docs</a>, <a href="#doxygen-separate_member_pages">separate_member_pages</a>,
-        <a href="#doxygen-tab_size">tab_size</a>, <a href="#doxygen-aliases">aliases</a>, <a href="#doxygen-optimize_output_for_c">optimize_output_for_c</a>, <a href="#doxygen-optimize_output_java">optimize_output_java</a>, <a href="#doxygen-optimize_for_fortran">optimize_for_fortran</a>,
-        <a href="#doxygen-optimize_output_vhdl">optimize_output_vhdl</a>, <a href="#doxygen-optimize_output_slice">optimize_output_slice</a>, <a href="#doxygen-extension_mapping">extension_mapping</a>, <a href="#doxygen-markdown_support">markdown_support</a>,
-        <a href="#doxygen-toc_include_headings">toc_include_headings</a>, <a href="#doxygen-markdown_id_style">markdown_id_style</a>, <a href="#doxygen-autolink_support">autolink_support</a>, <a href="#doxygen-autolink_ignore_words">autolink_ignore_words</a>,
-        <a href="#doxygen-builtin_stl_support">builtin_stl_support</a>, <a href="#doxygen-cpp_cli_support">cpp_cli_support</a>, <a href="#doxygen-sip_support">sip_support</a>, <a href="#doxygen-idl_property_support">idl_property_support</a>, <a href="#doxygen-distribute_group_doc">distribute_group_doc</a>,
-        <a href="#doxygen-group_nested_compounds">group_nested_compounds</a>, <a href="#doxygen-subgrouping">subgrouping</a>, <a href="#doxygen-inline_grouped_classes">inline_grouped_classes</a>, <a href="#doxygen-inline_simple_structs">inline_simple_structs</a>,
-        <a href="#doxygen-typedef_hides_struct">typedef_hides_struct</a>, <a href="#doxygen-lookup_cache_size">lookup_cache_size</a>, <a href="#doxygen-num_proc_threads">num_proc_threads</a>, <a href="#doxygen-timestamp">timestamp</a>, <a href="#doxygen-extract_all">extract_all</a>,
-        <a href="#doxygen-extract_private">extract_private</a>, <a href="#doxygen-extract_priv_virtual">extract_priv_virtual</a>, <a href="#doxygen-extract_package">extract_package</a>, <a href="#doxygen-extract_static">extract_static</a>, <a href="#doxygen-extract_local_classes">extract_local_classes</a>,
-        <a href="#doxygen-extract_local_methods">extract_local_methods</a>, <a href="#doxygen-extract_anon_nspaces">extract_anon_nspaces</a>, <a href="#doxygen-resolve_unnamed_params">resolve_unnamed_params</a>, <a href="#doxygen-hide_undoc_members">hide_undoc_members</a>,
-        <a href="#doxygen-hide_undoc_classes">hide_undoc_classes</a>, <a href="#doxygen-hide_undoc_namespaces">hide_undoc_namespaces</a>, <a href="#doxygen-hide_friend_compounds">hide_friend_compounds</a>, <a href="#doxygen-hide_in_body_docs">hide_in_body_docs</a>,
-        <a href="#doxygen-internal_docs">internal_docs</a>, <a href="#doxygen-case_sense_names">case_sense_names</a>, <a href="#doxygen-hide_scope_names">hide_scope_names</a>, <a href="#doxygen-hide_compound_reference">hide_compound_reference</a>, <a href="#doxygen-show_headerfile">show_headerfile</a>,
+doxygen(<a href="#doxygen-name">name</a>, <a href="#doxygen-srcs">srcs</a>, <a href="#doxygen-deps">deps</a>, <a href="#doxygen-dot_executable">dot_executable</a>, <a href="#doxygen-configurations">configurations</a>, <a href="#doxygen-doxyfile_template">doxyfile_template</a>, <a href="#doxygen-doxygen_extra_args">doxygen_extra_args</a>,
+        <a href="#doxygen-outs">outs</a>, <a href="#doxygen-doxyfile_encoding">doxyfile_encoding</a>, <a href="#doxygen-project_name">project_name</a>, <a href="#doxygen-project_number">project_number</a>, <a href="#doxygen-project_brief">project_brief</a>, <a href="#doxygen-project_logo">project_logo</a>,
+        <a href="#doxygen-project_icon">project_icon</a>, <a href="#doxygen-create_subdirs">create_subdirs</a>, <a href="#doxygen-create_subdirs_level">create_subdirs_level</a>, <a href="#doxygen-allow_unicode_names">allow_unicode_names</a>, <a href="#doxygen-output_language">output_language</a>,
+        <a href="#doxygen-brief_member_desc">brief_member_desc</a>, <a href="#doxygen-repeat_brief">repeat_brief</a>, <a href="#doxygen-abbreviate_brief">abbreviate_brief</a>, <a href="#doxygen-always_detailed_sec">always_detailed_sec</a>, <a href="#doxygen-inline_inherited_memb">inline_inherited_memb</a>,
+        <a href="#doxygen-full_path_names">full_path_names</a>, <a href="#doxygen-strip_from_path">strip_from_path</a>, <a href="#doxygen-strip_from_inc_path">strip_from_inc_path</a>, <a href="#doxygen-short_names">short_names</a>, <a href="#doxygen-javadoc_autobrief">javadoc_autobrief</a>,
+        <a href="#doxygen-javadoc_banner">javadoc_banner</a>, <a href="#doxygen-qt_autobrief">qt_autobrief</a>, <a href="#doxygen-multiline_cpp_is_brief">multiline_cpp_is_brief</a>, <a href="#doxygen-python_docstring">python_docstring</a>, <a href="#doxygen-inherit_docs">inherit_docs</a>,
+        <a href="#doxygen-separate_member_pages">separate_member_pages</a>, <a href="#doxygen-tab_size">tab_size</a>, <a href="#doxygen-aliases">aliases</a>, <a href="#doxygen-optimize_output_for_c">optimize_output_for_c</a>, <a href="#doxygen-optimize_output_java">optimize_output_java</a>,
+        <a href="#doxygen-optimize_for_fortran">optimize_for_fortran</a>, <a href="#doxygen-optimize_output_vhdl">optimize_output_vhdl</a>, <a href="#doxygen-optimize_output_slice">optimize_output_slice</a>, <a href="#doxygen-extension_mapping">extension_mapping</a>,
+        <a href="#doxygen-markdown_support">markdown_support</a>, <a href="#doxygen-toc_include_headings">toc_include_headings</a>, <a href="#doxygen-markdown_id_style">markdown_id_style</a>, <a href="#doxygen-autolink_support">autolink_support</a>,
+        <a href="#doxygen-autolink_ignore_words">autolink_ignore_words</a>, <a href="#doxygen-builtin_stl_support">builtin_stl_support</a>, <a href="#doxygen-cpp_cli_support">cpp_cli_support</a>, <a href="#doxygen-sip_support">sip_support</a>,
+        <a href="#doxygen-idl_property_support">idl_property_support</a>, <a href="#doxygen-distribute_group_doc">distribute_group_doc</a>, <a href="#doxygen-group_nested_compounds">group_nested_compounds</a>, <a href="#doxygen-subgrouping">subgrouping</a>,
+        <a href="#doxygen-inline_grouped_classes">inline_grouped_classes</a>, <a href="#doxygen-inline_simple_structs">inline_simple_structs</a>, <a href="#doxygen-typedef_hides_struct">typedef_hides_struct</a>, <a href="#doxygen-lookup_cache_size">lookup_cache_size</a>,
+        <a href="#doxygen-num_proc_threads">num_proc_threads</a>, <a href="#doxygen-timestamp">timestamp</a>, <a href="#doxygen-extract_all">extract_all</a>, <a href="#doxygen-extract_private">extract_private</a>, <a href="#doxygen-extract_priv_virtual">extract_priv_virtual</a>,
+        <a href="#doxygen-extract_package">extract_package</a>, <a href="#doxygen-extract_static">extract_static</a>, <a href="#doxygen-extract_local_classes">extract_local_classes</a>, <a href="#doxygen-extract_local_methods">extract_local_methods</a>,
+        <a href="#doxygen-extract_anon_nspaces">extract_anon_nspaces</a>, <a href="#doxygen-resolve_unnamed_params">resolve_unnamed_params</a>, <a href="#doxygen-hide_undoc_members">hide_undoc_members</a>, <a href="#doxygen-hide_undoc_classes">hide_undoc_classes</a>,
+        <a href="#doxygen-hide_undoc_namespaces">hide_undoc_namespaces</a>, <a href="#doxygen-hide_friend_compounds">hide_friend_compounds</a>, <a href="#doxygen-hide_in_body_docs">hide_in_body_docs</a>, <a href="#doxygen-internal_docs">internal_docs</a>,
+        <a href="#doxygen-case_sense_names">case_sense_names</a>, <a href="#doxygen-hide_scope_names">hide_scope_names</a>, <a href="#doxygen-hide_compound_reference">hide_compound_reference</a>, <a href="#doxygen-show_headerfile">show_headerfile</a>,
         <a href="#doxygen-show_include_files">show_include_files</a>, <a href="#doxygen-show_grouped_memb_inc">show_grouped_memb_inc</a>, <a href="#doxygen-force_local_includes">force_local_includes</a>, <a href="#doxygen-inline_info">inline_info</a>,
         <a href="#doxygen-sort_member_docs">sort_member_docs</a>, <a href="#doxygen-sort_brief_docs">sort_brief_docs</a>, <a href="#doxygen-sort_members_ctors_1st">sort_members_ctors_1st</a>, <a href="#doxygen-sort_group_names">sort_group_names</a>,
         <a href="#doxygen-sort_by_scope_name">sort_by_scope_name</a>, <a href="#doxygen-strict_proto_matching">strict_proto_matching</a>, <a href="#doxygen-generate_todolist">generate_todolist</a>, <a href="#doxygen-generate_testlist">generate_testlist</a>,
@@ -85,25 +105,40 @@ Depending on the type of the attribute, the macro will convert it to the appropr
 - list: the value of the attribute is a string with the elements separated by spaces and enclosed in double quotes
 - str: the value of the attribute is will be set to the string, unchanged. You may need to provide proper quoting if the value contains spaces
 
+For the complete list of Doxygen configuration options, please refer to the [Doxygen documentation](https://www.doxygen.nl/manual/config.html).
+
 ### Example
 
-```starlark
+```bzl
 # MODULE.bazel file
 bazel_dep(name = "rules_doxygen", dev_dependency = True)
 doxygen_extension = use_extension("@rules_doxygen//:extensions.bzl", "doxygen_extension")
 use_repo(doxygen_extension, "doxygen")
 ```
 
-```starlark
+```bzl
 # BUILD.bazel file
 load("@doxygen//:doxygen.bzl", "doxygen")
+load("@rules_cc//cc:defs.bzl", "cc_library")
+
+cc_library(
+    name = "lib",
+    srcs = ["add.cpp", "sub.cpp"],
+    hdrs = ["add.h", "sub.h"],
+)
+
+cc_library(
+    name = "main",
+    srcs = ["main.cpp"],
+    deps = [":lib"],
+)
 
 doxygen(
     name = "doxygen",
     srcs = glob([
-        "*.h",
-        "*.cpp",
+        "*.md",
     ]),
+    deps = [":main"]
     aliases = [
         "licence=@par Licence:^^",
         "verb{1}=@verbatim \\1 @endverbatim",
@@ -121,7 +156,8 @@ doxygen(
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="doxygen-name"></a>name |  A name for the target.   |  none |
-| <a id="doxygen-srcs"></a>srcs |  A list of source files to generate documentation for.   |  none |
+| <a id="doxygen-srcs"></a>srcs |  A list of source files to generate documentation for.   |  `[]` |
+| <a id="doxygen-deps"></a>deps |  A list of dependencies whose source, header and data files, and those or the transitive dependencies, will be included in the documentation.   |  `[]` |
 | <a id="doxygen-dot_executable"></a>dot_executable |  Label of the doxygen executable. Make sure it is also added to the `srcs` of the macro   |  `None` |
 | <a id="doxygen-configurations"></a>configurations |  A list of additional configuration parameters to pass to Doxygen.   |  `None` |
 | <a id="doxygen-doxyfile_template"></a>doxyfile_template |  The template file to use to generate the Doxyfile. The following substitutions are available:<br> - `# {{INPUT}}`: Subpackage directory in the sandbox.<br> - `# {{ADDITIONAL PARAMETERS}}`: Additional parameters given in the `configurations` attribute.<br> - `# {{OUTPUT DIRECTORY}}`: The directory provided in the `outs` attribute.   |  `None` |
@@ -435,3 +471,25 @@ doxygen(
 | <a id="doxygen-kwargs"></a>kwargs |  Additional arguments to pass to the rule (e.g. `visibility = ["//visibility:public"], tags = ["manual"]`)   |  none |
 
 
+<a id="collect_files_aspect"></a>
+
+## collect_files_aspect
+
+<pre>
+load("@rules_doxygen//doxygen:doxygen.bzl", "collect_files_aspect")
+
+collect_files_aspect()
+</pre>
+
+When applied to a target, this aspect collects the source files from the target and its dependencies, and makes them available in the TransitiveSourcesInfo provider.
+
+**ASPECT ATTRIBUTES**
+
+
+| Name | Type |
+| :------------- | :------------- |
+| deps| String |
+
+
+
+

docs/extensions_doc.md

@@ -72,7 +72,7 @@ You can further customize the repository by specifying the `doxygen_bzl`, `build
 
 ### Example
 
-```starlark
+```bzl
 # Download the os specific version 1.12.0 of doxygen supporting all the indicated platforms
 doxygen_repository(
     name = "doxygen",
@@ -180,7 +180,7 @@ No download will be performed, and the file indicated by the label will be used
 
 ### Examples
 
-```starlark
+```bzl
 # MODULE.bazel file
 
 bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)
@@ -198,7 +198,7 @@ doxygen_extension.configuration(
 use_repo(doxygen_extension, "doxygen")
 ```
 
-```starlark
+```bzl
 # MODULE.bazel file
 
 bazel_dep(name = "rules_doxygen", version = "...", dev_dependency = True)