cmDocumentation: Add diagnostics

Teach cmDocumentation to provide help for diagnostics. Teach cmRST about
the new diagnostic role and directive.

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] "
     "[<file>]",
@@ -39,6 +39,12 @@ cmDocumentationEntry const cmDocumentationStandardOptions[21] = {
   { "--help-command-list [<file>]",
     "List commands with help available and exit." },
   { "--help-commands [<file>]", "Print cmake-commands manual and exit." },
+  { "--help-diagnostic <diag> [<file>]",
+    "Print help for one diagnostic and exit." },
+  { "--help-diagnostic-list [<file>]",
+    "List diagnostics with help available and exit." },
+  { "--help-diagnostics [<file>]",
+    "Print cmake-diagnostics manual and exit." },
   { "--help-module <mod> [<file>]", "Print help for one module and exit." },
   { "--help-module-list [<file>]",
     "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;

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);

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|"