1 /*============================================================================
2 CMake - Cross Platform Makefile Generator
3 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
5 Distributed under the OSI-approved BSD License (the "License");
6 see accompanying file Copyright.txt for details.
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
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"
31 /** Class to generate documentation. */
32 class cmDocumentation: public cmDocumentationEnums
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
47 typedef std::pair<std::string,std::string> documentedModuleSectionPair_t;
49 * A list of documented module(s).
51 typedef std::list<documentedModuleSectionPair_t> documentedModulesList_t;
53 // High-level interface for standard documents:
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
63 bool CheckOptions(int argc, const char* const* argv,
64 const char* exitOpt =0);
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.
72 bool PrintRequestedDocumentation(std::ostream& os);
74 /** Print help of the given type. */
75 bool PrintDocumentation(Type ht, std::ostream& os, const char* docname=0);
77 void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; }
79 /** Set the program name for standard document generation. */
80 void SetName(const char* name);
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 *>
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);
108 * Print documentation in the given form. All previously added
109 * sections will be generated.
111 void Print(Form f, int manSection, std::ostream& os);
114 * Print documentation in the current form. All previously added
115 * sections will be generated.
117 void Print(std::ostream& os);
120 * Add a section of documentation. This can be used to generate custom help
123 void AddSectionToPrint(const char *section);
125 void SetSeeAlsoList(const char *data[][3]);
127 /** Clear all previously added sections of help. */
128 void ClearSections();
130 /** Set cmake root so we can find installed files */
131 void SetCMakeRoot(const char* root) { this->CMakeRoot = root;}
133 /** Set CMAKE_MODULE_PATH so we can find additional cmake modules */
134 void SetCMakeModulePath(const char* path) { this->CMakeModulePath = path;}
136 static Form GetFormFromFilename(const std::string& filename,
139 /** Add common (to all tools) documentation section(s) */
140 void addCommonStandardDocSections();
142 /** Add the CMake standard documentation section(s) */
143 void addCMakeStandardDocSections();
145 /** Add the CTest standard documentation section(s) */
146 void addCTestStandardDocSections();
148 /** Add the CPack standard documentation section(s) */
149 void addCPackStandardDocSections();
151 /** Add automatic variables sections */
152 void addAutomaticVariableSections(const std::string& section);
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
164 int getDocumentedModulesListInDir(
166 std::string globExpr,
167 documentedModulesList_t& docModuleList);
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
187 * @return the number of documented items (command and variable)
190 int GetStructuredDocFromFile(const char* fname,
191 std::vector<cmDocumentationEntry>& commands,
194 void SetForm(Form f, int manSection);
195 void SetDocName(const char* docname);
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();
206 void AddDocumentIntroToPrint(const char* intro[2]);
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);
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;
237 std::string NameString;
239 std::map<std::string,cmDocumentationSection*> AllSections;
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;
249 struct RequestedHelpItem
251 RequestedHelpItem():HelpForm(TextForm), HelpType(None), ManSection(1) {}
252 cmDocumentationEnums::Form HelpForm;
253 cmDocumentationEnums::Type HelpType;
254 std::string Filename;
255 std::string Argument;
259 std::vector<RequestedHelpItem> RequestedHelpItems;
260 cmDocumentationFormatter* CurrentFormatter;
261 cmDocumentationFormatterHTML HTMLFormatter;
262 cmDocumentationFormatterDocbook DocbookFormatter;
263 cmDocumentationFormatterMan ManFormatter;
264 cmDocumentationFormatterText TextFormatter;
265 cmDocumentationFormatterUsage UsageFormatter;
267 std::vector<std::string> PropertySections;
268 std::vector<std::string> VariableSections;