[Test, do not merge] Generated API Reference at o3de::development commit:7dfbca

[chanmosq]

Change summary

This PR includes the generated API reference for the development branch of o3de. See the commit message for the last commit in o3de::development` that the API reference was generated on.

Submission Checklist:

• Descriptive active voice - Do descriptive sentences have a clear subject and action verb?
• Answer the question at hand - Does the documentation answer a what, why, how, or where type of question?
• Consistency - Does the content consistently follow the Style Guide?
• Help the user - Does the documentation show the user something meaningful?

Details about generating API Ref

Checking for broken links

I use the following method to check for broken links in the API Reference:

1. Installed Markdown Link Checker, using Rust and a Linux system:

cargo install mlc

2. Ran mlc on the O3DE API Reference.

mlc o3de.org/static/docs/api

Issue: A protected member has a broken link to a private class, but docs are not generated for private members

This issue assumes that we don't want to generate API reference for private members.

Case 1

This issue occurred at commit cb91000

Summary: In this case a public class was generating a link to it's a protected member's private base class.
Details:

The AzFramework::Spawnable::EntityAliasConstVisitor API ref links to a private class that it's protected fields inherit from, EntityAliasVisitorBase. The link produces 404 error because an API ref was not generated for EntityAliasVisitorBase, as that is a private class.

To avoid generating an API for protected classes at all, I made a few changes to the doxygen script by setting the following configurations:

EXTRACT_PRIVATE = NO
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = protected=private

⚠This solution assumes that we want to avoid generating API Reference for protected members. Unsure if that is what we want.

Case 2

This issue occurred at commit a286533, after updating the doxygen script as described in Case 1

Summary: In this case, a struct linked to a protected base class, which didn't produce an API ref, as expected.
Details:
The AZ::DocumentPropertyEditor::ValueStringSort::StringSortNode API ref links to a protected class it inherits from, AZ::DocumentPropertyEditor::RowSortAdapter::SortInfoBase. However, the link produces 404 because an API ref was not generated for SortInfoBase struct as that is a a protected struct.

• At this commit, the broken link for SortInfoBase points to struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html, which can be found here.
• However, an API ref was generated for SortInfoNode struct, which is also protected, so it's unclear why SortInfoBase didn't produce an API ref.

Generating API reference for private members

This update occurs at commit b2cb5b4, but has been since reverted due to an offline discussion in favor of not generating an API reference for private members.

This update assumes that we want to generate API references for private members. With this update, both cases of the above issue are resolved, resulting in no broken links. Originally, EXTRACT_PRIVATE was set to NO to avoid noise in the API from private members.

To generate an API for private members, I made a few changes to the doxygen script by setting the following configurations:

EXTRACT_PRIVATE = YES
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
PREDEFINED =

Improving the mainpage of each API Reference

This update occurs at commit e133ab6.

Investigation for improving the mainpage, or index.html, of each API Reference. A doxygen mainpage is defined by using the /mainpage command in a doxygen comment. Following this model, each O3DE framework and Gem needs to define their own mainpage. Because the API Reference is created in conjunction with a Gem Reference page, or another page in the O3DE User Guide, we don't use doxygen to create the mainpage. Instead, we must set up a generic mainpage template that doxygen generates for every API Reference.

As of this commit, the mainpage template looks like the following image. It contains hardcoded links to the most common pages that doxygen generates. This is a prototype of the experience and may contain broken links.

The challenge is that we don't know what pages are available for each API Reference (frameworks and Gems) until Doxygen generates them. However, it generates their mainpage at the same time. So, a possible solution is to post-process the mainpage with an updated list of the available Doxygen-generated docs.

[chanmosq]

Broken links as of commit cb91000

In o3de.org/content/docs/api/frameworks:

./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (62, 200) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (64, 184) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (66, 185) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (68, 183) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (70, 182) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (73, 202) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (75, 199) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (76, 176) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (79, 262) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor-members.html (80, 264) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (63, 213) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (65, 197) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (67, 198) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (69, 196) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (71, 195) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (76, 189) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (78, 186) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (81, 189) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (84, 249) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor-members.html (85, 277) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor.html (73, 106) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_const_visitor.html (104, 311) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor.html (134, 106) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzFramework/class_az_framework_1_1_spawnable_1_1_entity_alias_visitor.html (144, 311) => class_az_framework_1_1_spawnable_1_1_entity_alias_visitor_base.html
./static/docs/api/frameworks/AzQtComponents/index.html (45, 392) => https://o3de.org/docs/tools-ui/ui-dev-intro/
./static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_compressor.html (89, 218) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression
./static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_networking.html (100, 585) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression
./static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_compressor_factory.html (74, 792) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression

Broken links as of commit a286533

In o3de.org/content/docs/api/frameworks:

o3de.org/static/docs/api/frameworks/AzFramework/struct_a_z_1_1_document_property_editor_1_1_value_string_sort_1_1_string_sort_node.html (70, 342) => struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html
o3de.org/static/docs/api/frameworks/AzFramework/struct_a_z_1_1_document_property_editor_1_1_value_string_sort_1_1_string_sort_node.html (84, 206) => struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html
o3de.org/static/docs/api/frameworks/AzFramework/struct_a_z_1_1_document_property_editor_1_1_value_string_sort_1_1_string_sort_node-members.html (64, 160) => struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html
o3de.org/static/docs/api/frameworks/AzFramework/struct_a_z_1_1_document_property_editor_1_1_value_string_sort_1_1_string_sort_node-members.html (68, 198) => struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html
o3de.org/static/docs/api/frameworks/AzFramework/struct_a_z_1_1_document_property_editor_1_1_value_string_sort_1_1_string_sort_node-members.html (69, 177) => struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html
o3de.org/static/docs/api/frameworks/AzFramework/struct_a_z_1_1_document_property_editor_1_1_value_string_sort_1_1_string_sort_node-members.html (70, 179) => struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html
o3de.org/static/docs/api/frameworks/AzFramework/struct_a_z_1_1_document_property_editor_1_1_value_string_sort_1_1_string_sort_node-members.html (72, 165) => struct_a_z_1_1_document_property_editor_1_1_row_sort_adapter_1_1_sort_info_base.html
o3de.org/static/docs/api/frameworks/AzQtComponents/index.html (45, 392) => https://o3de.org/docs/tools-ui/ui-dev-intro/
o3de.org/static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_compressor.html (89, 218) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression
o3de.org/static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_networking.html (100, 585) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression
o3de.org/static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_compressor_factory.html (74, 792) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression

In o3de.org/content/docs/api/gems:

o3de.org/static/docs/api/gems/ROS2/class_r_o_s2_1_1_lidar_raycaster_requests.html (199, 652) => https://github.com/RobotecAI/RobotecGPULidar/blob/v11/docs/GaussianNoise.md

Broken links as of commit b2cb5b4

Only api/frameworks was regenerated for this commit, not api/gems.

❗ As opposed to the last two commits, this commit generates API reference for all private members.

o3de.org/static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_compressor.html (89, 218) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression
o3de.org/static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_networking.html (100, 585) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression
o3de.org/static/docs/api/frameworks/AzNetworking/class_az_networking_1_1_i_compressor_factory.html (74, 792) => http://o3de.org/docs/user-guide/gems/reference/multiplayer-compression
o3de.org/static/docs/api/frameworks/frameworks/AzQtComponents/index.html (45, 392) => https://o3de.org/docs/tools-ui/ui-dev-intro/

[chanmosq]

Closing this test PR.

The generated C++ API reference for O3DE version 2305 is available at #2359
The scripts and documentation used are published at o3de/sig-docs-community#112