Teach --help-* options to load documentation from .rst files

Install the Help directory next to Modules to make it available in CMake
distributions.  Use cmRST to read Help .rst documents and print them as
help output.

Add options

 --help-manual-list
 --help-manual

to list available manuals or print one of them.  Implement the options

 --help-commands
 --help-modules
 --help-policies
 --help-properties
 --help-variables

by mapping to the corresponding manual page.  Implement the options

 --help-command-list
 --help-module-list
 --help-policy-list
 --help-property-list
 --help-variable-list

by globbing the available Help .rst documents of the corresponding type
and reading their titles.  Implement the options

 --help-command
 --help-module
 --help-policy
 --help-property
 --help-variable

by globbing the matching Help .rst document(s) and printing them.
This commit is contained in:
Brad King 2013-09-16 11:29:06 -04:00
parent 25f2877eef
commit ec6df3675e
6 changed files with 309 additions and 37 deletions

View File

@ -582,7 +582,7 @@ install(FILES Copyright.txt DESTINATION ${CMAKE_DOC_DIR})
# Install script directories. # Install script directories.
install( install(
DIRECTORY Modules Templates DIRECTORY Help Modules Templates
DESTINATION ${CMAKE_DATA_DIR} DESTINATION ${CMAKE_DATA_DIR}
FILE_PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ FILE_PERMISSIONS OWNER_READ OWNER_WRITE GROUP_READ WORLD_READ
DIRECTORY_PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE DIRECTORY_PERMISSIONS OWNER_READ OWNER_EXECUTE OWNER_WRITE

View File

@ -13,9 +13,13 @@
#include "cmSystemTools.h" #include "cmSystemTools.h"
#include "cmVersion.h" #include "cmVersion.h"
#include "cmRST.h"
#include <cmsys/Directory.hxx> #include <cmsys/Directory.hxx>
#include <cmsys/Glob.hxx> #include <cmsys/Glob.hxx>
#include <ctype.h>
#include <algorithm> #include <algorithm>
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
@ -101,22 +105,30 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
{ {
case cmDocumentation::Usage: case cmDocumentation::Usage:
return this->PrintDocumentationUsage(os); return this->PrintDocumentationUsage(os);
case cmDocumentation::Single: case cmDocumentation::OneManual:
case cmDocumentation::SingleModule: return this->PrintHelpOneManual(os);
case cmDocumentation::SinglePolicy: case cmDocumentation::OneCommand:
case cmDocumentation::SingleProperty: return this->PrintHelpOneCommand(os);
case cmDocumentation::SingleVariable: case cmDocumentation::OneModule:
case cmDocumentation::List: return this->PrintHelpOneModule(os);
case cmDocumentation::ModuleList: case cmDocumentation::OnePolicy:
case cmDocumentation::PropertyList: return this->PrintHelpOnePolicy(os);
case cmDocumentation::VariableList: case cmDocumentation::OneProperty:
case cmDocumentation::PolicyList: return this->PrintHelpOneProperty(os);
case cmDocumentation::Modules: case cmDocumentation::OneVariable:
case cmDocumentation::Policies: return this->PrintHelpOneVariable(os);
case cmDocumentation::Properties: case cmDocumentation::ListManuals:
case cmDocumentation::Variables: return this->PrintHelpListManuals(os);
case cmDocumentation::Commands: case cmDocumentation::ListCommands:
return false; return this->PrintHelpListCommands(os);
case cmDocumentation::ListModules:
return this->PrintHelpListModules(os);
case cmDocumentation::ListProperties:
return this->PrintHelpListProperties(os);
case cmDocumentation::ListVariables:
return this->PrintHelpListVariables(os);
case cmDocumentation::ListPolicies:
return this->PrintHelpListPolicies(os);
case cmDocumentation::Version: case cmDocumentation::Version:
return this->PrintVersion(os); return this->PrintVersion(os);
default: return false; default: return false;
@ -126,6 +138,7 @@ bool cmDocumentation::PrintDocumentation(Type ht, std::ostream& os)
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os) bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os)
{ {
int count = 0;
bool result = true; bool result = true;
// Loop over requested documentation types. // Loop over requested documentation types.
@ -152,6 +165,10 @@ bool cmDocumentation::PrintRequestedDocumentation(std::ostream& os)
result = false; result = false;
} }
} }
else if(++count > 1)
{
os << "\n\n";
}
// Print this documentation type to the stream. // Print this documentation type to the stream.
if(!this->PrintDocumentation(i->HelpType, *s) || !*s) if(!this->PrintDocumentation(i->HelpType, *s) || !*s)
@ -287,33 +304,37 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
// special case for single command // special case for single command
if (!help.Argument.empty()) if (!help.Argument.empty())
{ {
help.HelpType = cmDocumentation::Single; help.HelpType = cmDocumentation::OneCommand;
} }
} }
else if(strcmp(argv[i], "--help-properties") == 0) else if(strcmp(argv[i], "--help-properties") == 0)
{ {
help.HelpType = cmDocumentation::Properties; help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-properties.7";
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection); &help.ManSection);
} }
else if(strcmp(argv[i], "--help-policies") == 0) else if(strcmp(argv[i], "--help-policies") == 0)
{ {
help.HelpType = cmDocumentation::Policies; help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-policies.7";
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection); &help.ManSection);
} }
else if(strcmp(argv[i], "--help-variables") == 0) else if(strcmp(argv[i], "--help-variables") == 0)
{ {
help.HelpType = cmDocumentation::Variables; help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-variables.7";
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection); &help.ManSection);
} }
else if(strcmp(argv[i], "--help-modules") == 0) else if(strcmp(argv[i], "--help-modules") == 0)
{ {
help.HelpType = cmDocumentation::Modules; help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-modules.7";
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection); &help.ManSection);
@ -327,7 +348,8 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
} }
else if(strcmp(argv[i], "--help-commands") == 0) else if(strcmp(argv[i], "--help-commands") == 0)
{ {
help.HelpType = cmDocumentation::Commands; help.HelpType = cmDocumentation::OneManual;
help.Argument = "cmake-commands.7";
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection); &help.ManSection);
@ -359,7 +381,7 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
} }
else if(strcmp(argv[i], "--help-command") == 0) else if(strcmp(argv[i], "--help-command") == 0)
{ {
help.HelpType = cmDocumentation::Single; help.HelpType = cmDocumentation::OneCommand;
GET_OPT_ARGUMENT(help.Argument); GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.Argument = cmSystemTools::LowerCase(help.Argument); help.Argument = cmSystemTools::LowerCase(help.Argument);
@ -368,7 +390,7 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
} }
else if(strcmp(argv[i], "--help-module") == 0) else if(strcmp(argv[i], "--help-module") == 0)
{ {
help.HelpType = cmDocumentation::SingleModule; help.HelpType = cmDocumentation::OneModule;
GET_OPT_ARGUMENT(help.Argument); GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
@ -376,7 +398,7 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
} }
else if(strcmp(argv[i], "--help-property") == 0) else if(strcmp(argv[i], "--help-property") == 0)
{ {
help.HelpType = cmDocumentation::SingleProperty; help.HelpType = cmDocumentation::OneProperty;
GET_OPT_ARGUMENT(help.Argument); GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
@ -384,7 +406,7 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
} }
else if(strcmp(argv[i], "--help-policy") == 0) else if(strcmp(argv[i], "--help-policy") == 0)
{ {
help.HelpType = cmDocumentation::SinglePolicy; help.HelpType = cmDocumentation::OnePolicy;
GET_OPT_ARGUMENT(help.Argument); GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
@ -392,42 +414,54 @@ bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
} }
else if(strcmp(argv[i], "--help-variable") == 0) else if(strcmp(argv[i], "--help-variable") == 0)
{ {
help.HelpType = cmDocumentation::SingleVariable; help.HelpType = cmDocumentation::OneVariable;
GET_OPT_ARGUMENT(help.Argument); GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = this->GetFormFromFilename(help.Filename, help.HelpForm = this->GetFormFromFilename(help.Filename,
&help.ManSection); &help.ManSection);
} }
else if(strcmp(argv[i], "--help-manual") == 0)
{
help.HelpType = cmDocumentation::OneManual;
GET_OPT_ARGUMENT(help.Argument);
GET_OPT_ARGUMENT(help.Filename);
this->WarnFormFromFilename(help);
}
else if(strcmp(argv[i], "--help-command-list") == 0) else if(strcmp(argv[i], "--help-command-list") == 0)
{ {
help.HelpType = cmDocumentation::List; help.HelpType = cmDocumentation::ListCommands;
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm; help.HelpForm = cmDocumentation::TextForm;
} }
else if(strcmp(argv[i], "--help-module-list") == 0) else if(strcmp(argv[i], "--help-module-list") == 0)
{ {
help.HelpType = cmDocumentation::ModuleList; help.HelpType = cmDocumentation::ListModules;
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm; help.HelpForm = cmDocumentation::TextForm;
} }
else if(strcmp(argv[i], "--help-property-list") == 0) else if(strcmp(argv[i], "--help-property-list") == 0)
{ {
help.HelpType = cmDocumentation::PropertyList; help.HelpType = cmDocumentation::ListProperties;
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm; help.HelpForm = cmDocumentation::TextForm;
} }
else if(strcmp(argv[i], "--help-variable-list") == 0) else if(strcmp(argv[i], "--help-variable-list") == 0)
{ {
help.HelpType = cmDocumentation::VariableList; help.HelpType = cmDocumentation::ListVariables;
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm; help.HelpForm = cmDocumentation::TextForm;
} }
else if(strcmp(argv[i], "--help-policy-list") == 0) else if(strcmp(argv[i], "--help-policy-list") == 0)
{ {
help.HelpType = cmDocumentation::PolicyList; help.HelpType = cmDocumentation::ListPolicies;
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
help.HelpForm = cmDocumentation::TextForm; help.HelpForm = cmDocumentation::TextForm;
} }
else if(strcmp(argv[i], "--help-manual-list") == 0)
{
help.HelpType = cmDocumentation::ListManuals;
GET_OPT_ARGUMENT(help.Filename);
}
else if(strcmp(argv[i], "--copyright") == 0) else if(strcmp(argv[i], "--copyright") == 0)
{ {
GET_OPT_ARGUMENT(help.Filename); GET_OPT_ARGUMENT(help.Filename);
@ -616,6 +650,217 @@ void cmDocumentation::PrependSection(const char *name,
this->PrependSection(name,docsVec); this->PrependSection(name,docsVec);
} }
//----------------------------------------------------------------------------
void cmDocumentation::GlobHelp(std::vector<std::string>& files,
std::string const& pattern)
{
cmsys::Glob gl;
std::string findExpr = this->CMakeRoot + "/Help/" + pattern + ".rst";
if(gl.FindFiles(findExpr))
{
files = gl.GetFiles();
}
}
//----------------------------------------------------------------------------
void cmDocumentation::PrintNames(std::ostream& os,
std::string const& pattern)
{
std::vector<std::string> files;
this->GlobHelp(files, pattern);
std::vector<std::string> names;
for (std::vector<std::string>::const_iterator i = files.begin();
i != files.end(); ++i)
{
std::string line;
std::ifstream fin(i->c_str());
while(fin && cmSystemTools::GetLineFromStream(fin, line))
{
if(!line.empty() && (isalnum(line[0]) || line[0] == '<'))
{
names.push_back(line);
break;
}
}
}
std::sort(names.begin(), names.end());
for (std::vector<std::string>::iterator i = names.begin();
i != names.end(); ++i)
{
os << *i << "\n";
}
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintFiles(std::ostream& os,
std::string const& pattern)
{
bool found = false;
std::vector<std::string> files;
this->GlobHelp(files, pattern);
std::sort(files.begin(), files.end());
cmRST r(os, this->CMakeRoot + "/Help");
for (std::vector<std::string>::const_iterator i = files.begin();
i != files.end(); ++i)
{
found = r.ProcessFile(i->c_str()) || found;
}
return found;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpOneManual(std::ostream& os)
{
std::string mname = this->CurrentArgument;
std::string::size_type mlen = mname.length();
if(mlen > 3 && mname[mlen-3] == '(' &&
mname[mlen-1] == ')')
{
mname = mname.substr(0, mlen-3) + "." + mname[mlen-2];
}
if(this->PrintFiles(os, "manual/" + mname) ||
this->PrintFiles(os, "manual/" + mname + ".[0-9]"))
{
return true;
}
// Argument was not a manual. Complain.
os << "Argument \"" << this->CurrentArgument.c_str()
<< "\" to --help-manual is not an available manual. "
<< "Use --help-manual-list to see all available manuals.\n";
return false;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpListManuals(std::ostream& os)
{
this->PrintNames(os, "manual/*");
return true;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpOneCommand(std::ostream& os)
{
std::string cname = cmSystemTools::LowerCase(this->CurrentArgument);
if(this->PrintFiles(os, "command/" + cname))
{
return true;
}
// Argument was not a command. Complain.
os << "Argument \"" << this->CurrentArgument.c_str()
<< "\" to --help-command is not a CMake command. "
<< "Use --help-command-list to see all commands.\n";
return false;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpListCommands(std::ostream& os)
{
this->PrintNames(os, "command/*");
return true;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpOneModule(std::ostream& os)
{
std::string mname = this->CurrentArgument;
if(this->PrintFiles(os, "module/" + mname))
{
return true;
}
// Argument was not a module. Complain.
os << "Argument \"" << this->CurrentArgument.c_str()
<< "\" to --help-module is not a CMake module.\n";
return false;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpListModules(std::ostream& os)
{
std::vector<std::string> files;
this->GlobHelp(files, "module/*");
std::vector<std::string> modules;
for (std::vector<std::string>::iterator fi = files.begin();
fi != files.end(); ++fi)
{
std::string module = cmSystemTools::GetFilenameName(*fi);
modules.push_back(module.substr(0, module.size()-4));
}
std::sort(modules.begin(), modules.end());
for (std::vector<std::string>::iterator i = modules.begin();
i != modules.end(); ++i)
{
os << *i << "\n";
}
return true;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpOneProperty(std::ostream& os)
{
std::string pname = cmSystemTools::HelpFileName(this->CurrentArgument);
if(this->PrintFiles(os, "prop_*/" + pname))
{
return true;
}
// Argument was not a property. Complain.
os << "Argument \"" << this->CurrentArgument.c_str()
<< "\" to --help-property is not a CMake property. "
<< "Use --help-property-list to see all properties.\n";
return false;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpListProperties(std::ostream& os)
{
this->PrintNames(os, "prop_*/*");
return true;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpOnePolicy(std::ostream& os)
{
std::string pname = this->CurrentArgument;
std::vector<std::string> files;
if(this->PrintFiles(os, "policy/" + pname))
{
return true;
}
// Argument was not a policy. Complain.
os << "Argument \"" << this->CurrentArgument.c_str()
<< "\" to --help-policy is not a CMake policy.\n";
return false;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpListPolicies(std::ostream& os)
{
this->PrintNames(os, "policy/*");
return true;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpOneVariable(std::ostream& os)
{
std::string vname = cmSystemTools::HelpFileName(this->CurrentArgument);
if(this->PrintFiles(os, "variable/" + vname))
{
return true;
}
// Argument was not a variable. Complain.
os << "Argument \"" << this->CurrentArgument.c_str()
<< "\" to --help-variable is not a defined variable. "
<< "Use --help-variable-list to see all defined variables.\n";
return false;
}
//----------------------------------------------------------------------------
bool cmDocumentation::PrintHelpListVariables(std::ostream& os)
{
this->PrintNames(os, "variable/*");
return true;
}
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
bool cmDocumentation::PrintDocumentationUsage(std::ostream& os) bool cmDocumentation::PrintDocumentationUsage(std::ostream& os)
{ {

View File

@ -131,7 +131,23 @@ public:
private: private:
void SetForm(Form f, int manSection); void SetForm(Form f, int manSection);
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 PrintVersion(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 PrintDocumentationUsage(std::ostream& os); bool PrintDocumentationUsage(std::ostream& os);
const char* GetNameString() const; const char* GetNameString() const;

View File

@ -25,10 +25,11 @@ class cmDocumentationEnums
public: public:
/** Types of help provided. */ /** Types of help provided. */
enum Type enum Type
{ None, Usage, Single, SingleModule, SingleProperty, SingleVariable, {
List, ModuleList, PropertyList, VariableList, PolicyList, None, Version, Usage, ListManuals,
Properties, Variables, Modules, Commands, ListCommands, ListModules, ListProperties, ListVariables, ListPolicies,
Copyright, Version, Policies, SinglePolicy }; OneManual, OneCommand, OneModule, OneProperty, OneVariable, OnePolicy
};
/** Forms of documentation output. */ /** Forms of documentation output. */
enum Form { TextForm, HTMLForm, RSTForm, ManForm, UsageForm, DocbookForm }; enum Form { TextForm, HTMLForm, RSTForm, ManForm, UsageForm, DocbookForm };

View File

@ -200,6 +200,13 @@ std::string cmSystemTools::EscapeQuotes(const char* str)
return result; return result;
} }
std::string cmSystemTools::HelpFileName(std::string name)
{
cmSystemTools::ReplaceString(name, "<", "");
cmSystemTools::ReplaceString(name, ">", "");
return name;
}
std::string cmSystemTools::TrimWhitespace(const std::string& s) std::string cmSystemTools::TrimWhitespace(const std::string& s)
{ {
std::string::const_iterator start = s.begin(); std::string::const_iterator start = s.begin();

View File

@ -49,6 +49,9 @@ public:
///! Escape quotes in a string. ///! Escape quotes in a string.
static std::string EscapeQuotes(const char* str); static std::string EscapeQuotes(const char* str);
/** Map help document name to file name. */
static std::string HelpFileName(std::string);
/** /**
* Returns a string that has whitespace removed from the start and the end. * Returns a string that has whitespace removed from the start and the end.
*/ */