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 Copyright.txt 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, const char* const* argv,
const char* 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(const std::string& name);
/** Set a section of the documentation. Typical sections include Name,
Usage, Description, Options */
void SetSection(const char* sectionName, cmDocumentationSection section);
template <typename Iterable>
void SetSection(const char* sectionName, const Iterable& 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(const char* sectionName, const Iterable& docs)
{
this->SectionAtName(sectionName).Prepend(docs);
}
void PrependSection(const char* sectionName, cmDocumentationEntry& docs);
template <typename Iterable>
void AppendSection(const char* sectionName, const Iterable& docs)
{
this->SectionAtName(sectionName).Append(docs);
}
void AppendSection(const char* 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);
const char* GetNameString() const;
bool ShowGenerators;
std::string NameString;
std::map<std::string, cmDocumentationSection> AllSections;
cmDocumentationSection& SectionAtName(const char* 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);
};
|