diff options
Diffstat (limited to 'Source/cmDocumentation.h')
| -rw-r--r-- | Source/cmDocumentation.h | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/Source/cmDocumentation.h b/Source/cmDocumentation.h new file mode 100644 index 0000000..e180f60 --- /dev/null +++ b/Source/cmDocumentation.h @@ -0,0 +1,271 @@ +/*============================================================================ + 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, int manSection, 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, + int* ManSection); + + /** 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(); + + /** Add automatic variables sections */ + void addAutomaticVariableSections(const std::string& section); + + /** + * 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); +private: + void SetForm(Form f, int manSection); + 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), ManSection(1) {} + cmDocumentationEnums::Form HelpForm; + cmDocumentationEnums::Type HelpType; + std::string Filename; + std::string Argument; + int ManSection; + }; + + 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 |