Source/cmDocumentation.h

   1 /* Distributed under the OSI-approved BSD 3-Clause License.  See accompanying
   2    file Copyright.txt or https://cmake.org/licensing for details.  */
   3 #pragma once
   4
   5 #include "cmConfigure.h" // IWYU pragma: keep
   6
   7 #include <iosfwd>
   8 #include <map>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "cmDocumentationFormatter.h"
  13 #include "cmDocumentationSection.h"
  14
  15 struct cmDocumentationEntry;
  16
  17 /** Class to generate documentation.  */
  18 class cmDocumentation : public cmDocumentationEnums
  19 {
  20 public:
  21   cmDocumentation();
  22
  23   /**
  24    * Check command line arguments for documentation options.  Returns
  25    * true if documentation options are found, and false otherwise.
  26    * When true is returned, PrintRequestedDocumentation should be
  27    * called.  exitOpt can be used for things like cmake -E, so that
  28    * all arguments after the -E are ignored and not searched for
  29    * help arguments.
  30    */
  31   bool CheckOptions(int argc, const char* const* argv,
  32                     const char* exitOpt = nullptr);
  33
  34   /**
  35    * Print help requested on the command line.  Call after
  36    * CheckOptions returns true.  Returns true on success, and false
  37    * otherwise.  Failure can occur when output files specified on the
  38    * command line cannot be written.
  39    */
  40   bool PrintRequestedDocumentation(std::ostream& os);
  41
  42   /** Print help of the given type.  */
  43   bool PrintDocumentation(Type ht, std::ostream& os);
  44
  45   void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; }
  46
  47   /** Set the program name for standard document generation.  */
  48   void SetName(const std::string& name);
  49
  50   /** Set a section of the documentation. Typical sections include Name,
  51       Usage, Description, Options */
  52   void SetSection(const char* sectionName, cmDocumentationSection section);
  53   void SetSection(const char* sectionName,
  54                   std::vector<cmDocumentationEntry>& docs);
  55   void SetSection(const char* sectionName, const char* docs[][2]);
  56   void SetSections(std::map<std::string, cmDocumentationSection> sections);
  57
  58   /** Add the documentation to the beginning/end of the section */
  59   void PrependSection(const char* sectionName, const char* docs[][2]);
  60   void PrependSection(const char* sectionName,
  61                       std::vector<cmDocumentationEntry>& docs);
  62   void PrependSection(const char* sectionName, cmDocumentationEntry& docs);
  63   void AppendSection(const char* sectionName, const char* docs[][2]);
  64   void AppendSection(const char* sectionName,
  65                      std::vector<cmDocumentationEntry>& docs);
  66   void AppendSection(const char* sectionName, cmDocumentationEntry& docs);
  67
  68   /** Add common (to all tools) documentation section(s) */
  69   void addCommonStandardDocSections();
  70
  71   /** Add the CMake standard documentation section(s) */
  72   void addCMakeStandardDocSections();
  73
  74   /** Add the CTest standard documentation section(s) */
  75   void addCTestStandardDocSections();
  76
  77   /** Add the CPack standard documentation section(s) */
  78   void addCPackStandardDocSections();
  79
  80 private:
  81   void GlobHelp(std::vector<std::string>& files, std::string const& pattern);
  82   void PrintNames(std::ostream& os, std::string const& pattern);
  83   bool PrintFiles(std::ostream& os, std::string const& pattern);
  84
  85   bool PrintVersion(std::ostream& os);
  86   bool PrintUsage(std::ostream& os);
  87   bool PrintHelp(std::ostream& os);
  88   bool PrintHelpFull(std::ostream& os);
  89   bool PrintHelpOneManual(std::ostream& os);
  90   bool PrintHelpOneCommand(std::ostream& os);
  91   bool PrintHelpOneModule(std::ostream& os);
  92   bool PrintHelpOnePolicy(std::ostream& os);
  93   bool PrintHelpOneProperty(std::ostream& os);
  94   bool PrintHelpOneVariable(std::ostream& os);
  95   bool PrintHelpListManuals(std::ostream& os);
  96   bool PrintHelpListCommands(std::ostream& os);
  97   bool PrintHelpListModules(std::ostream& os);
  98   bool PrintHelpListProperties(std::ostream& os);
  99   bool PrintHelpListVariables(std::ostream& os);
 100   bool PrintHelpListPolicies(std::ostream& os);
 101   bool PrintHelpListGenerators(std::ostream& os);
 102   bool PrintOldCustomModules(std::ostream& os);
 103
 104   const char* GetNameString() const;
 105   bool IsOption(const char* arg) const;
 106
 107   bool ShowGenerators;
 108
 109   std::string NameString;
 110   std::map<std::string, cmDocumentationSection> AllSections;
 111   cmDocumentationSection& SectionAtName(const char* name);
 112
 113   std::string CurrentArgument;
 114
 115   struct RequestedHelpItem
 116   {
 117     cmDocumentationEnums::Type HelpType = None;
 118     std::string Filename;
 119     std::string Argument;
 120   };
 121
 122   std::vector<RequestedHelpItem> RequestedHelpItems;
 123   cmDocumentationFormatter Formatter;
 124
 125   static void WarnFormFromFilename(RequestedHelpItem& request, bool& result);
 126 };