From a882ec84ec09d30d203183c8f4af540f514df646 Mon Sep 17 00:00:00 2001 From: Matthew Woehlke Date: Thu, 30 Apr 2026 15:27:44 -0400 Subject: [PATCH] cmDocumentation: Add diagnostics Teach cmDocumentation to provide help for diagnostics. Teach cmRST about the new diagnostic role and directive. --- Source/cmDocumentation.cxx | 45 +++++++++++++++++++++++++++++++++++++- Source/cmDocumentation.h | 4 ++++ Source/cmRST.cxx | 4 ++-- 3 files changed, 50 insertions(+), 3 deletions(-) diff --git a/Source/cmDocumentation.cxx b/Source/cmDocumentation.cxx index 66e3730dcf..0cc2b64d07 100644 --- a/Source/cmDocumentation.cxx +++ b/Source/cmDocumentation.cxx @@ -26,7 +26,7 @@ #include "cmVersion.h" namespace { -cmDocumentationEntry const cmDocumentationStandardOptions[21] = { +cmDocumentationEntry const cmDocumentationStandardOptions[] = { { "-h,-H,--help,-help,-usage,/?", "Print usage information and exit." }, { "--version[=json-v1],-version[=json-v1],/V[=json-v1],/version[=json-v1] " "[]", @@ -39,6 +39,12 @@ cmDocumentationEntry const cmDocumentationStandardOptions[21] = { { "--help-command-list []", "List commands with help available and exit." }, { "--help-commands []", "Print cmake-commands manual and exit." }, + { "--help-diagnostic []", + "Print help for one diagnostic and exit." }, + { "--help-diagnostic-list []", + "List diagnostics with help available and exit." }, + { "--help-diagnostics []", + "Print cmake-diagnostics manual and exit." }, { "--help-module []", "Print help for one module and exit." }, { "--help-module-list []", "List modules with help available and exit." }, @@ -164,6 +170,8 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os) return this->PrintHelpOneManual(os); case cmDocumentation::OneCommand: return this->PrintHelpOneCommand(os); + case cmDocumentation::OneDiagnostic: + return this->PrintHelpOneDiagnostic(os); case cmDocumentation::OneModule: return this->PrintHelpOneModule(os); case cmDocumentation::OnePolicy: @@ -176,6 +184,8 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os) return this->PrintHelpListManuals(os); case cmDocumentation::ListCommands: return this->PrintHelpListCommands(os); + case cmDocumentation::ListDiagnostics: + return this->PrintHelpListDiagnostics(os); case cmDocumentation::ListModules: return this->PrintHelpListModules(os); case cmDocumentation::ListProperties: @@ -377,6 +387,11 @@ bool cmDocumentation::CheckOptions(int argc, char const* const* argv, cmSystemTools::Message( "Warning: --help-compatcommands no longer supported"); return true; + } else if (strcmp(argv[i], "--help-diagnostics") == 0) { + help.HelpType = cmDocumentation::OneManual; + help.Argument = "cmake-diagnostics.7"; + i += int(get_opt_argument(i + 1, help.Filename)); + this->WarnFormFromFilename(help, result); } else if (strcmp(argv[i], "--help-full") == 0) { help.HelpType = cmDocumentation::Full; i += int(get_opt_argument(i + 1, help.Filename)); @@ -393,6 +408,12 @@ bool cmDocumentation::CheckOptions(int argc, char const* const* argv, i += int(get_opt_argument(i + 1, help.Filename)); help.Argument = cmSystemTools::LowerCase(help.Argument); this->WarnFormFromFilename(help, result); + } else if (strcmp(argv[i], "--help-diagnostic") == 0) { + help.HelpType = cmDocumentation::OneDiagnostic; + i += int(get_opt_argument(i + 1, help.Argument)); + i += int(get_opt_argument(i + 1, help.Filename)); + help.Argument = cmSystemTools::UpperCase(help.Argument); + this->WarnFormFromFilename(help, result); } else if (strcmp(argv[i], "--help-module") == 0) { help.HelpType = cmDocumentation::OneModule; i += int(get_opt_argument(i + 1, help.Argument)); @@ -421,6 +442,9 @@ bool cmDocumentation::CheckOptions(int argc, char const* const* argv, } else if (strcmp(argv[i], "--help-command-list") == 0) { help.HelpType = cmDocumentation::ListCommands; i += int(get_opt_argument(i + 1, help.Filename)); + } else if (strcmp(argv[i], "--help-diagnostic-list") == 0) { + help.HelpType = cmDocumentation::ListDiagnostics; + i += int(get_opt_argument(i + 1, help.Filename)); } else if (strcmp(argv[i], "--help-module-list") == 0) { help.HelpType = cmDocumentation::ListModules; i += int(get_opt_argument(i + 1, help.Filename)); @@ -622,6 +646,25 @@ bool cmDocumentation::PrintHelpListCommands(std::ostream& os) return true; } +bool cmDocumentation::PrintHelpOneDiagnostic(std::ostream& os) +{ + std::string dname = cmSystemTools::UpperCase(this->CurrentArgument); + if (this->PrintFiles(os, cmStrCat("diagnostic/", dname))) { + return true; + } + // Argument was not a command. Complain. + os << "Argument \"" << this->CurrentArgument + << "\" to --help-command is not a CMake diagnostic. " + "Use --help-diagnostic-list to see all diagnostics.\n"; + return false; +} + +bool cmDocumentation::PrintHelpListDiagnostics(std::ostream& os) +{ + this->PrintNames(os, "diagnostic/*"); + return true; +} + bool cmDocumentation::PrintHelpOneModule(std::ostream& os) { std::string mname = this->CurrentArgument; diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h index dd0fadba0f..e23cee9fe9 100644 --- a/Source/cmDocumentation.h +++ b/Source/cmDocumentation.h @@ -30,6 +30,7 @@ public: Full, ListManuals, ListCommands, + ListDiagnostics, ListModules, ListProperties, ListVariables, @@ -38,6 +39,7 @@ public: OneArbitrary, OneManual, OneCommand, + OneDiagnostic, OneModule, OneProperty, OneVariable, @@ -124,12 +126,14 @@ private: bool PrintHelpOneArbitrary(std::ostream& os); bool PrintHelpOneManual(std::ostream& os); bool PrintHelpOneCommand(std::ostream& os); + bool PrintHelpOneDiagnostic(std::ostream& os); bool PrintHelpOneModule(std::ostream& os); bool PrintHelpOnePolicy(std::ostream& os); bool PrintHelpOneProperty(std::ostream& os); bool PrintHelpOneVariable(std::ostream& os); bool PrintHelpListManuals(std::ostream& os); bool PrintHelpListCommands(std::ostream& os); + bool PrintHelpListDiagnostics(std::ostream& os); bool PrintHelpListModules(std::ostream& os); bool PrintHelpListProperties(std::ostream& os); bool PrintHelpListVariables(std::ostream& os); diff --git a/Source/cmRST.cxx b/Source/cmRST.cxx index e49037099e..0d3f3bcfe2 100644 --- a/Source/cmRST.cxx +++ b/Source/cmRST.cxx @@ -20,7 +20,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot) : OS(os) , DocRoot(std::move(docroot)) , CMakeDirective("^.. (cmake:)?(" - "command|envvar|genex|signature|variable" + "command|diagnostic|envvar|genex|signature|variable" ")::") , CMakeModuleDirective("^.. cmake-module::[ \t]+([^ \t\n]+)$") , ParsedLiteralDirective("^.. parsed-literal::[ \t]*(.*)$") @@ -34,7 +34,7 @@ cmRST::cmRST(std::ostream& os, std::string docroot) , ModuleRST(R"(^#\[(=*)\[\.rst:$)") , CMakeRole("(:cmake)?:(" "cref|" - "command|cpack_gen|generator|genex|" + "command|cpack_gen|diagnostic|generator|genex|" "variable|envvar|module|policy|" "prop_cache|prop_dir|prop_gbl|prop_inst|prop_sf|" "prop_test|prop_tgt|"