Source/cmDocumentation.h

   1 /*============================================================================
   2   CMake - Cross Platform Makefile Generator
   3   Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
   4
   5   Distributed under the OSI-approved BSD License (the "License");
   6   see accompanying file Copyright.txt for details.
   7
   8   This software is distributed WITHOUT ANY WARRANTY; without even the
   9   implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  10   See the License for more information.
  11 ============================================================================*/
  12 #ifndef _cmDocumentation_h
  13 #define _cmDocumentation_h
  14
  15 #include "cmStandardIncludes.h"
  16 #include "cmProperty.h"
  17 #include "cmDocumentationFormatter.h"
  18 #include "cmDocumentationFormatterHTML.h"
  19 #include "cmDocumentationFormatterDocbook.h"
  20 #include "cmDocumentationFormatterMan.h"
  21 #include "cmDocumentationFormatterText.h"
  22 #include "cmDocumentationFormatterUsage.h"
  23 #include "cmDocumentationSection.h"
  24 #include "cmake.h"
  25
  26 namespace cmsys
  27 {
  28   class Directory;
  29 }
  30
  31 /** Class to generate documentation.  */
  32 class cmDocumentation: public cmDocumentationEnums
  33 {
  34 public:
  35   cmDocumentation();
  36
  37   ~cmDocumentation();
  38
  39   /**
  40    * An helper type pair for [structured] documented modules.
  41    * The comment of those module contains structure markup
  42    * which makes it possible to retrieve the documentation
  43    * of variables, macros and functions defined in the module.
  44    * - first is the filename of the module
  45    * - second is the section of the doc the module belongs too
  46    */
  47   typedef std::pair<std::string,std::string> documentedModuleSectionPair_t;
  48   /**
  49    * A list of documented module(s).
  50    */
  51   typedef std::list<documentedModuleSectionPair_t>  documentedModulesList_t;
  52
  53   // High-level interface for standard documents:
  54
  55   /**
  56    * Check command line arguments for documentation options.  Returns
  57    * true if documentation options are found, and false otherwise.
  58    * When true is returned, PrintRequestedDocumentation should be
  59    * called.  exitOpt can be used for things like cmake -E, so that
  60    * all arguments after the -E are ignored and not searched for
  61    * help arguments.
  62    */
  63   bool CheckOptions(int argc, const char* const* argv,
  64                     const char* exitOpt =0);
  65
  66   /**
  67    * Print help requested on the command line.  Call after
  68    * CheckOptions returns true.  Returns true on success, and false
  69    * otherwise.  Failure can occur when output files specified on the
  70    * command line cannot be written.
  71    */
  72   bool PrintRequestedDocumentation(std::ostream& os);
  73
  74   /** Print help of the given type.  */
  75   bool PrintDocumentation(Type ht, std::ostream& os, const char* docname=0);
  76
  77   void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; }
  78
  79   /** Set the program name for standard document generation.  */
  80   void SetName(const char* name);
  81
  82   /** Set a section of the documentation. Typical sections include Name,
  83       Usage, Description, Options, SeeAlso */
  84   void SetSection(const char *sectionName,
  85                   cmDocumentationSection *section);
  86   void SetSection(const char *sectionName,
  87                   std::vector<cmDocumentationEntry> &docs);
  88   void SetSection(const char *sectionName,
  89                   const char *docs[][3]);
  90   void SetSections(std::map<std::string,cmDocumentationSection *>
  91                    &sections);
  92
  93   /** Add the documentation to the beginning/end of the section */
  94   void PrependSection(const char *sectionName,
  95                       const char *docs[][3]);
  96   void PrependSection(const char *sectionName,
  97                       std::vector<cmDocumentationEntry> &docs);
  98   void PrependSection(const char *sectionName,
  99                       cmDocumentationEntry &docs);
 100   void AppendSection(const char *sectionName,
 101                      const char *docs[][3]);
 102   void AppendSection(const char *sectionName,
 103                      std::vector<cmDocumentationEntry> &docs);
 104   void AppendSection(const char *sectionName,
 105                      cmDocumentationEntry &docs);
 106
 107   /**
 108    * Print documentation in the given form.  All previously added
 109    * sections will be generated.
 110    */
 111   void Print(Form f, int manSection, std::ostream& os);
 112
 113   /**
 114    * Print documentation in the current form.  All previously added
 115    * sections will be generated.
 116    */
 117   void Print(std::ostream& os);
 118
 119   /**
 120    * Add a section of documentation. This can be used to generate custom help
 121    * documents.
 122    */
 123   void AddSectionToPrint(const char *section);
 124
 125   void SetSeeAlsoList(const char *data[][3]);
 126
 127   /** Clear all previously added sections of help.  */
 128   void ClearSections();
 129
 130   /** Set cmake root so we can find installed files */
 131   void SetCMakeRoot(const char* root)  { this->CMakeRoot = root;}
 132
 133   /** Set CMAKE_MODULE_PATH so we can find additional cmake modules */
 134   void SetCMakeModulePath(const char* path)  { this->CMakeModulePath = path;}
 135
 136   static Form GetFormFromFilename(const std::string& filename,
 137                                   int* ManSection);
 138
 139   /** Add common (to all tools) documentation section(s) */
 140   void addCommonStandardDocSections();
 141
 142   /** Add the CMake standard documentation section(s) */
 143   void addCMakeStandardDocSections();
 144
 145   /** Add the CTest standard documentation section(s) */
 146   void addCTestStandardDocSections();
 147
 148   /** Add the CPack standard documentation section(s) */
 149   void addCPackStandardDocSections();
 150
 151   /** Add automatic variables sections */
 152   void addAutomaticVariableSections(const std::string& section);
 153
 154   /**
 155    * Retrieve the list of documented module located in
 156    * path which match the globing expression globExpr.
 157    * @param[in] path, directory where to start the search
 158    *                  we will recurse into it.
 159    * @param[in] globExpr, the globing expression used to
 160    *                      match the file in path.
 161    * @param[out] the list of obtained pairs (may be empty)
 162    * @return 0 on success 1 on error or empty list
 163    */
 164   int getDocumentedModulesListInDir(
 165           std::string path,
 166           std::string globExpr,
 167           documentedModulesList_t& docModuleList);
 168
 169   /**
 170    * Get the documentation of macros, functions and variable documented
 171    * with CMake structured documentation in a CMake script.
 172    * (in fact it may be in any file which follow the structured doc format)
 173    * Structured documentation begin with
 174    * ## (double sharp) in column 1 & 2 immediately followed
 175    * by a markup. Those ## are ignored by the legacy module
 176    * documentation parser @see CreateSingleModule.
 177    * Current markup are ##section, ##module,
 178    * ##macro, ##function, ##variable and ##end.
 179    * ##end is closing either of the previous ones.
 180    * @param[in] fname the script file name to be parsed for documentation
 181    * @param[in,out] commands the vector of command/macros documentation
 182    *                entry found in the script file.
 183    * @param[in,out] the cmake object instance to which variable documentation
 184    *                will be attached (using @see cmake::DefineProperty)
 185    * @param[in] the documentation section in which the property will be
 186    *            inserted.
 187    * @return the number of documented items (command and variable)
 188    *         found in the file.
 189    */
 190   int GetStructuredDocFromFile(const char* fname,
 191                                std::vector<cmDocumentationEntry>& commands,
 192                                cmake* cm);
 193 private:
 194   void SetForm(Form f, int manSection);
 195   void SetDocName(const char* docname);
 196
 197   bool CreateSingleModule(const char* fname,
 198                           const char* moduleName,
 199                           cmDocumentationSection &sec);
 200   void CreateModuleDocsForDir(cmsys::Directory& dir,
 201                               cmDocumentationSection &moduleSection);
 202   bool CreateModulesSection();
 203   bool CreateCustomModulesSection();
 204   void CreateFullDocumentation();
 205
 206   void AddDocumentIntroToPrint(const char* intro[2]);
 207
 208   bool PrintCopyright(std::ostream& os);
 209   bool PrintVersion(std::ostream& os);
 210   bool PrintDocumentationGeneric(std::ostream& os, const char *section);
 211   bool PrintDocumentationList(std::ostream& os, const char *section);
 212   bool PrintDocumentationSingle(std::ostream& os);
 213   bool PrintDocumentationSingleModule(std::ostream& os);
 214   bool PrintDocumentationSingleProperty(std::ostream& os);
 215   bool PrintDocumentationSinglePolicy(std::ostream& os);
 216   bool PrintDocumentationSingleVariable(std::ostream& os);
 217   bool PrintDocumentationUsage(std::ostream& os);
 218   bool PrintDocumentationFull(std::ostream& os);
 219   bool PrintDocumentationModules(std::ostream& os);
 220   bool PrintDocumentationCustomModules(std::ostream& os);
 221   bool PrintDocumentationPolicies(std::ostream& os);
 222   bool PrintDocumentationProperties(std::ostream& os);
 223   bool PrintDocumentationVariables(std::ostream& os);
 224   bool PrintDocumentationCurrentCommands(std::ostream& os);
 225   bool PrintDocumentationCompatCommands(std::ostream& os);
 226   void PrintDocumentationCommand(std::ostream& os,
 227                                  const cmDocumentationEntry &entry);
 228
 229
 230   const char* GetNameString() const;
 231   const char* GetDocName(bool fallbackToNameString = true) const;
 232   const char* GetDefaultDocName(Type ht) const;
 233   bool IsOption(const char* arg) const;
 234
 235   bool ShowGenerators;
 236
 237   std::string NameString;
 238   std::string DocName;
 239   std::map<std::string,cmDocumentationSection*> AllSections;
 240
 241   std::string SeeAlsoString;
 242   std::string CMakeRoot;
 243   std::string CMakeModulePath;
 244   std::set<std::string> ModulesFound;
 245   std::vector< char* > ModuleStrings;
 246   std::vector<const cmDocumentationSection *> PrintSections;
 247   std::string CurrentArgument;
 248
 249   struct RequestedHelpItem
 250   {
 251     RequestedHelpItem():HelpForm(TextForm), HelpType(None), ManSection(1) {}
 252     cmDocumentationEnums::Form HelpForm;
 253     cmDocumentationEnums::Type HelpType;
 254     std::string Filename;
 255     std::string Argument;
 256     int ManSection;
 257   };
 258
 259   std::vector<RequestedHelpItem> RequestedHelpItems;
 260   cmDocumentationFormatter* CurrentFormatter;
 261   cmDocumentationFormatterHTML HTMLFormatter;
 262   cmDocumentationFormatterDocbook DocbookFormatter;
 263   cmDocumentationFormatterMan ManFormatter;
 264   cmDocumentationFormatterText TextFormatter;
 265   cmDocumentationFormatterUsage UsageFormatter;
 266
 267   std::vector<std::string> PropertySections;
 268   std::vector<std::string> VariableSections;
 269 };
 270
 271 #endif