Add support for GNATdoc command-line options in GPR project files

[Heziode]

Add support for GNATdoc command-line options in GPR project files

Summary

Currently, GNATdoc requires users to specify various options through command-line arguments. It would be beneficial to support these options directly within GPR project files to improve project configuration management and reproducibility.

Current Situation

GNATdoc supports numerous command-line options such as:

• --output-dir for specifying output directory
• --backend for selecting output format (HTML/RST)
• --generate for selecting entity visibility level
• --style for documentation comment style
• --warnings for enabling missing documentation warnings
• Various other options for project configuration

Based on the documentation, there is already partial support for GPR project file configuration:

• Documentation'Output_Dir attribute is supported (as mentioned in the --output-dir option description)

However, most other options must still be specified each time GNATdoc is invoked, making it difficult to maintain consistent documentation generation across team members and CI/CD pipelines.

Proposed Enhancement

Expand the existing GPR project file support to include all major GNATdoc command-line options. Currently, only Documentation'Output_Dir is documented as supported. The enhancement would add support for attributes such as:

project My_Project is
   package Documentation is
      for Output_Dir use "docs";                    -- Already supported
      for Backend use "html";                       -- New: html, rst
      for Generate use "public";                    -- New: public, private, body
      for Style use "gnat";                         -- New: leading, trailing, gnat
      for Warnings use "true";                      -- New: enable warnings
      for Verbose use "false";                      -- New: enable verbose output
   end Documentation;
end My_Project;

Benefits

1. Consistency: All team members use the same documentation generation settings
2. Maintainability: Configuration is version-controlled alongside the project
3. CI/CD Integration: Simplified automation without complex command-line argument management
4. Project Self-Documentation: Documentation settings are visible in the project structure

Alternative

If more GPR attributes are already supported beyond Documentation'Output_Dir, please update the documentation to clearly describe:

• Complete list of available GPR attributes for GNATdoc configuration
• Examples of common use cases for each attribute
• How GPR settings interact with command-line options (precedence rules)
• Valid values for each attribute (e.g., backend options, generate options, style options)

The current documentation only mentions Documentation'Output_Dir but doesn't provide a comprehensive reference for project-level GNATdoc configuration.

Real-world Use Case

In my current workflow, I use VS Code with the Ada extension for development. The IDE's hover functionality appears to use either GNAT or trailing style for extracting documentation comments, but my project uses leading style comments (documentation before entity declarations). This mismatch causes the IDE to display incorrect or missing documentation when hovering over elements like packages.

Having the ability to specify for Style use "leading"; in the GPR file would allow the Ada toolchain (including IDE integrations) to consistently use the correct documentation style across all tools, ensuring that:

• GNATdoc generates proper documentation
• IDE hover tooltips show the correct comments
• All team members see consistent documentation regardless of their tooling

This highlights the importance of project-level configuration for documentation settings, as different projects may legitimately use different documentation styles, and all tools should respect the project's chosen convention.