1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
/* Distributed under the OSI-approved BSD 3-Clause License. See accompanying
file LICENSE.rst or https://cmake.org/licensing for details. */
#pragma once
#include "cmConfigure.h" // IWYU pragma: keep
#include <iosfwd>
#include <map>
#include <string>
#include <utility>
#include <vector>
#include "cmDocumentationFormatter.h"
#include "cmDocumentationSection.h"
struct cmDocumentationEntry;
/** Class to generate documentation. */
class cmDocumentation
{
public:
/** Types of help provided. */
enum Type
{
None,
Version,
Usage,
Help,
Full,
ListManuals,
ListCommands,
ListModules,
ListProperties,
ListVariables,
ListPolicies,
ListGenerators,
OneArbitrary,
OneManual,
OneCommand,
OneModule,
OneProperty,
OneVariable,
OnePolicy,
OldCustomModules
};
cmDocumentation();
/**
* Check command line arguments for documentation options. Returns
* true if documentation options are found, and false otherwise.
* When true is returned, PrintRequestedDocumentation should be
* called. exitOpt can be used for things like cmake -E, so that
* all arguments after the -E are ignored and not searched for
* help arguments.
*/
bool CheckOptions(int argc, char const* const* argv,
char const* exitOpt = nullptr);
/**
* Print help requested on the command line. Call after
* CheckOptions returns true. Returns true on success, and false
* otherwise. Failure can occur when output files specified on the
* command line cannot be written.
*/
bool PrintRequestedDocumentation(std::ostream& os);
/** Print help of the given type. */
bool PrintDocumentation(Type ht, std::ostream& os);
void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; }
/** Set the program name for standard document generation. */
void SetName(std::string const& name);
/** Set a section of the documentation. Typical sections include Name,
Usage, Description, Options */
void SetSection(char const* sectionName, cmDocumentationSection section);
template <typename Iterable>
void SetSection(char const* sectionName, Iterable const& docs)
{
cmDocumentationSection sec{ sectionName };
sec.Append(docs);
this->SetSection(sectionName, std::move(sec));
}
/** Add the documentation to the beginning/end of the section */
template <typename Iterable>
void PrependSection(char const* sectionName, Iterable const& docs)
{
this->SectionAtName(sectionName).Prepend(docs);
}
void PrependSection(char const* sectionName, cmDocumentationEntry& docs);
template <typename Iterable>
void AppendSection(char const* sectionName, Iterable const& docs)
{
this->SectionAtName(sectionName).Append(docs);
}
void AppendSection(char const* sectionName, cmDocumentationEntry& docs);
/** Add common (to all tools) documentation section(s) */
void addCommonStandardDocSections();
/** Add the CMake standard documentation section(s) */
void addCMakeStandardDocSections();
/** Add the CTest standard documentation section(s) */
void addCTestStandardDocSections();
/** Add the CPack standard documentation section(s) */
void addCPackStandardDocSections();
private:
void GlobHelp(std::vector<std::string>& files, std::string const& pattern);
void PrintNames(std::ostream& os, std::string const& pattern);
bool PrintFiles(std::ostream& os, std::string const& pattern);
bool PrintVersion(std::ostream& os);
bool PrintUsage(std::ostream& os);
bool PrintHelp(std::ostream& os);
bool PrintHelpFull(std::ostream& os);
bool PrintHelpOneArbitrary(std::ostream& os);
bool PrintHelpOneManual(std::ostream& os);
bool PrintHelpOneCommand(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 PrintHelpListModules(std::ostream& os);
bool PrintHelpListProperties(std::ostream& os);
bool PrintHelpListVariables(std::ostream& os);
bool PrintHelpListPolicies(std::ostream& os);
bool PrintHelpListGenerators(std::ostream& os);
bool PrintOldCustomModules(std::ostream& os);
char const* GetNameString() const;
bool ShowGenerators;
std::string NameString;
std::map<std::string, cmDocumentationSection> AllSections;
cmDocumentationSection& SectionAtName(char const* name);
std::string CurrentArgument;
struct RequestedHelpItem
{
Type HelpType = None;
std::string Filename;
std::string Argument;
};
std::vector<RequestedHelpItem> RequestedHelpItems;
cmDocumentationFormatter Formatter;
static void WarnFormFromFilename(RequestedHelpItem& request, bool& result);
static std::string GeneralizeKeyword(std::string word);
};
|
