268 lines
9.9 KiB
C++
268 lines
9.9 KiB
C++
/*============================================================================
|
|
CMake - Cross Platform Makefile Generator
|
|
Copyright 2000-2009 Kitware, Inc., Insight Software Consortium
|
|
|
|
Distributed under the OSI-approved BSD License (the "License");
|
|
see accompanying file Copyright.txt for details.
|
|
|
|
This software is distributed WITHOUT ANY WARRANTY; without even the
|
|
implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
See the License for more information.
|
|
============================================================================*/
|
|
#ifndef _cmDocumentation_h
|
|
#define _cmDocumentation_h
|
|
|
|
#include "cmStandardIncludes.h"
|
|
#include "cmProperty.h"
|
|
#include "cmDocumentationFormatter.h"
|
|
#include "cmDocumentationFormatterHTML.h"
|
|
#include "cmDocumentationFormatterDocbook.h"
|
|
#include "cmDocumentationFormatterMan.h"
|
|
#include "cmDocumentationFormatterText.h"
|
|
#include "cmDocumentationFormatterUsage.h"
|
|
#include "cmDocumentationSection.h"
|
|
#include "cmake.h"
|
|
|
|
namespace cmsys
|
|
{
|
|
class Directory;
|
|
}
|
|
|
|
/** Class to generate documentation. */
|
|
class cmDocumentation: public cmDocumentationEnums
|
|
{
|
|
public:
|
|
cmDocumentation();
|
|
|
|
~cmDocumentation();
|
|
|
|
/**
|
|
* An helper type pair for [structured] documented modules.
|
|
* The comment of those module contains structure markup
|
|
* which makes it possible to retrieve the documentation
|
|
* of variables, macros and functions defined in the module.
|
|
* - first is the filename of the module
|
|
* - second is the section of the doc the module belongs too
|
|
*/
|
|
typedef std::pair<std::string,std::string> documentedModuleSectionPair_t;
|
|
/**
|
|
* A list of documented module(s).
|
|
*/
|
|
typedef std::list<documentedModuleSectionPair_t> documentedModulesList_t;
|
|
|
|
// High-level interface for standard documents:
|
|
|
|
/**
|
|
* 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 =0);
|
|
|
|
/**
|
|
* 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, const char* docname=0);
|
|
|
|
void SetShowGenerators(bool showGen) { this->ShowGenerators = showGen; }
|
|
|
|
/** Set the program name for standard document generation. */
|
|
void SetName(const char* name);
|
|
|
|
/** Set a section of the documentation. Typical sections include Name,
|
|
Usage, Description, Options, SeeAlso */
|
|
void SetSection(const char *sectionName,
|
|
cmDocumentationSection *section);
|
|
void SetSection(const char *sectionName,
|
|
std::vector<cmDocumentationEntry> &docs);
|
|
void SetSection(const char *sectionName,
|
|
const char *docs[][3]);
|
|
void SetSections(std::map<std::string,cmDocumentationSection *>
|
|
§ions);
|
|
|
|
/** Add the documentation to the beginning/end of the section */
|
|
void PrependSection(const char *sectionName,
|
|
const char *docs[][3]);
|
|
void PrependSection(const char *sectionName,
|
|
std::vector<cmDocumentationEntry> &docs);
|
|
void PrependSection(const char *sectionName,
|
|
cmDocumentationEntry &docs);
|
|
void AppendSection(const char *sectionName,
|
|
const char *docs[][3]);
|
|
void AppendSection(const char *sectionName,
|
|
std::vector<cmDocumentationEntry> &docs);
|
|
void AppendSection(const char *sectionName,
|
|
cmDocumentationEntry &docs);
|
|
|
|
/**
|
|
* Print documentation in the given form. All previously added
|
|
* sections will be generated.
|
|
*/
|
|
void Print(Form f, std::ostream& os);
|
|
|
|
/**
|
|
* Print documentation in the current form. All previously added
|
|
* sections will be generated.
|
|
*/
|
|
void Print(std::ostream& os);
|
|
|
|
/**
|
|
* Add a section of documentation. This can be used to generate custom help
|
|
* documents.
|
|
*/
|
|
void AddSectionToPrint(const char *section);
|
|
|
|
void SetSeeAlsoList(const char *data[][3]);
|
|
|
|
/** Clear all previously added sections of help. */
|
|
void ClearSections();
|
|
|
|
/** Set cmake root so we can find installed files */
|
|
void SetCMakeRoot(const char* root) { this->CMakeRoot = root;}
|
|
|
|
/** Set CMAKE_MODULE_PATH so we can find additional cmake modules */
|
|
void SetCMakeModulePath(const char* path) { this->CMakeModulePath = path;}
|
|
|
|
static Form GetFormFromFilename(const std::string& filename);
|
|
|
|
/** 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();
|
|
|
|
/**
|
|
* Retrieve the list of documented module located in
|
|
* path which match the globing expression globExpr.
|
|
* @param[in] path, directory where to start the search
|
|
* we will recurse into it.
|
|
* @param[in] globExpr, the globing expression used to
|
|
* match the file in path.
|
|
* @param[out] the list of obtained pairs (may be empty)
|
|
* @return 0 on success 1 on error or empty list
|
|
*/
|
|
int getDocumentedModulesListInDir(
|
|
std::string path,
|
|
std::string globExpr,
|
|
documentedModulesList_t& docModuleList);
|
|
|
|
/**
|
|
* Get the documentation of macros, functions and variable documented
|
|
* with CMake structured documentation in a CMake script.
|
|
* (in fact it may be in any file which follow the structured doc format)
|
|
* Structured documentation begin with
|
|
* ## (double sharp) in column 1 & 2 immediately followed
|
|
* by a markup. Those ## are ignored by the legacy module
|
|
* documentation parser @see CreateSingleModule.
|
|
* Current markup are ##section, ##module,
|
|
* ##macro, ##function, ##variable and ##end.
|
|
* ##end is closing either of the previous ones.
|
|
* @param[in] fname the script file name to be parsed for documentation
|
|
* @param[in,out] commands the vector of command/macros documentation
|
|
* entry found in the script file.
|
|
* @param[in,out] the cmake object instance to which variable documentation
|
|
* will be attached (using @see cmake::DefineProperty)
|
|
* @param[in] the documentation section in which the property will be
|
|
* inserted.
|
|
* @return the number of documented items (command and variable)
|
|
* found in the file.
|
|
*/
|
|
int GetStructuredDocFromFile(const char* fname,
|
|
std::vector<cmDocumentationEntry>& commands,
|
|
cmake* cm,
|
|
const char *docSection);
|
|
private:
|
|
void SetForm(Form f);
|
|
void SetDocName(const char* docname);
|
|
|
|
bool CreateSingleModule(const char* fname,
|
|
const char* moduleName,
|
|
cmDocumentationSection &sec);
|
|
void CreateModuleDocsForDir(cmsys::Directory& dir,
|
|
cmDocumentationSection &moduleSection);
|
|
bool CreateModulesSection();
|
|
bool CreateCustomModulesSection();
|
|
void CreateFullDocumentation();
|
|
|
|
void AddDocumentIntroToPrint(const char* intro[2]);
|
|
|
|
bool PrintCopyright(std::ostream& os);
|
|
bool PrintVersion(std::ostream& os);
|
|
bool PrintDocumentationGeneric(std::ostream& os, const char *section);
|
|
bool PrintDocumentationList(std::ostream& os, const char *section);
|
|
bool PrintDocumentationSingle(std::ostream& os);
|
|
bool PrintDocumentationSingleModule(std::ostream& os);
|
|
bool PrintDocumentationSingleProperty(std::ostream& os);
|
|
bool PrintDocumentationSinglePolicy(std::ostream& os);
|
|
bool PrintDocumentationSingleVariable(std::ostream& os);
|
|
bool PrintDocumentationUsage(std::ostream& os);
|
|
bool PrintDocumentationFull(std::ostream& os);
|
|
bool PrintDocumentationModules(std::ostream& os);
|
|
bool PrintDocumentationCustomModules(std::ostream& os);
|
|
bool PrintDocumentationPolicies(std::ostream& os);
|
|
bool PrintDocumentationProperties(std::ostream& os);
|
|
bool PrintDocumentationVariables(std::ostream& os);
|
|
bool PrintDocumentationCurrentCommands(std::ostream& os);
|
|
bool PrintDocumentationCompatCommands(std::ostream& os);
|
|
void PrintDocumentationCommand(std::ostream& os,
|
|
const cmDocumentationEntry &entry);
|
|
|
|
|
|
const char* GetNameString() const;
|
|
const char* GetDocName(bool fallbackToNameString = true) const;
|
|
const char* GetDefaultDocName(Type ht) const;
|
|
bool IsOption(const char* arg) const;
|
|
|
|
bool ShowGenerators;
|
|
|
|
std::string NameString;
|
|
std::string DocName;
|
|
std::map<std::string,cmDocumentationSection*> AllSections;
|
|
|
|
std::string SeeAlsoString;
|
|
std::string CMakeRoot;
|
|
std::string CMakeModulePath;
|
|
std::set<std::string> ModulesFound;
|
|
std::vector< char* > ModuleStrings;
|
|
std::vector<const cmDocumentationSection *> PrintSections;
|
|
std::string CurrentArgument;
|
|
|
|
struct RequestedHelpItem
|
|
{
|
|
RequestedHelpItem():HelpForm(TextForm), HelpType(None) {}
|
|
cmDocumentationEnums::Form HelpForm;
|
|
cmDocumentationEnums::Type HelpType;
|
|
std::string Filename;
|
|
std::string Argument;
|
|
};
|
|
|
|
std::vector<RequestedHelpItem> RequestedHelpItems;
|
|
cmDocumentationFormatter* CurrentFormatter;
|
|
cmDocumentationFormatterHTML HTMLFormatter;
|
|
cmDocumentationFormatterDocbook DocbookFormatter;
|
|
cmDocumentationFormatterMan ManFormatter;
|
|
cmDocumentationFormatterText TextFormatter;
|
|
cmDocumentationFormatterUsage UsageFormatter;
|
|
|
|
std::vector<std::string> PropertySections;
|
|
std::vector<std::string> VariableSections;
|
|
};
|
|
|
|
#endif
|