Drop CPack module documentation markup extraction
This will be replaced by alternative markup later.
This commit is contained in:
Brad King
parent
946f0efb7c
commit
0d0fec1524
@ -541,27 +541,6 @@ int main (int argc, char *argv[])
|
|||||||
|
|
||||||
std::vector<cmDocumentationEntry> commands;
|
std::vector<cmDocumentationEntry> commands;
|
||||||
|
|
||||||
std::string docedFile;
|
|
||||||
std::string docPath;
|
|
||||||
cmDocumentation::documentedModulesList_t docedModList;
|
|
||||||
|
|
||||||
docedFile = globalMF->GetModulesFile("CPack.cmake");
|
|
||||||
if (docedFile.length()!=0)
|
|
||||||
{
|
|
||||||
docPath = cmSystemTools::GetFilenamePath(docedFile.c_str());
|
|
||||||
doc.getDocumentedModulesListInDir(docPath,"CPack*.cmake",docedModList);
|
|
||||||
}
|
|
||||||
|
|
||||||
// parse the files for documentation.
|
|
||||||
cmDocumentation::documentedModulesList_t::iterator docedIt;
|
|
||||||
for (docedIt = docedModList.begin();
|
|
||||||
docedIt!= docedModList.end(); ++docedIt)
|
|
||||||
{
|
|
||||||
doc.GetStructuredDocFromFile(
|
|
||||||
(docedIt->first).c_str(),
|
|
||||||
commands,&cminst);
|
|
||||||
}
|
|
||||||
|
|
||||||
std::map<std::string,cmDocumentationSection *> propDocs;
|
std::map<std::string,cmDocumentationSection *> propDocs;
|
||||||
cminst.GetPropertiesDocumentation(propDocs);
|
cminst.GetPropertiesDocumentation(propDocs);
|
||||||
doc.SetSections(propDocs);
|
doc.SetSections(propDocs);
|
||||||
|
|||||||
@ -502,8 +502,6 @@ bool cmDocumentation::CreateSingleModule(const char* fname,
|
|||||||
{
|
{
|
||||||
if(line.size() && line[0] == '#')
|
if(line.size() && line[0] == '#')
|
||||||
{
|
{
|
||||||
/* line beginnings with ## are mark-up ignore them */
|
|
||||||
if (line.size()>=2 && line[1] == '#') continue;
|
|
||||||
// blank line
|
// blank line
|
||||||
if(line.size() <= 2)
|
if(line.size() <= 2)
|
||||||
{
|
{
|
||||||
@ -750,331 +748,6 @@ void cmDocumentation::addAutomaticVariableSections(const std::string& section)
|
|||||||
this->VariableSections.push_back(section);
|
this->VariableSections.push_back(section);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
//----------------------------------------------------------------------------
|
|
||||||
int cmDocumentation::getDocumentedModulesListInDir(
|
|
||||||
std::string path,
|
|
||||||
std::string globExpr,
|
|
||||||
documentedModulesList_t& docedModuleList)
|
|
||||||
{
|
|
||||||
cmsys::Glob gl;
|
|
||||||
std::string findExpr;
|
|
||||||
std::vector<std::string> files;
|
|
||||||
std::string line;
|
|
||||||
documentedModuleSectionPair_t docPair;
|
|
||||||
int nbDocumentedModules = 0;
|
|
||||||
|
|
||||||
findExpr = path + "/" + globExpr;
|
|
||||||
if (gl.FindFiles(findExpr))
|
|
||||||
{
|
|
||||||
files = gl.GetFiles();
|
|
||||||
for (std::vector<std::string>::iterator itf=files.begin();
|
|
||||||
itf!=files.end();++itf)
|
|
||||||
{
|
|
||||||
std::ifstream fin((*itf).c_str());
|
|
||||||
// file access trouble ignore it (ignore this kind of error)
|
|
||||||
if (!fin) continue;
|
|
||||||
/* read first line in order to get doc section */
|
|
||||||
if (cmSystemTools::GetLineFromStream(fin, line))
|
|
||||||
{
|
|
||||||
/* Doc section indicates that
|
|
||||||
* this file has structured doc in it.
|
|
||||||
*/
|
|
||||||
if (line.find("##section")!=std::string::npos)
|
|
||||||
{
|
|
||||||
// ok found one more documented module
|
|
||||||
++nbDocumentedModules;
|
|
||||||
docPair.first = *itf;
|
|
||||||
// 10 is the size of '##section' + 1
|
|
||||||
docPair.second = line.substr(10,std::string::npos);
|
|
||||||
docedModuleList.push_back(docPair);
|
|
||||||
}
|
|
||||||
// No else if no section is found (undocumented module)
|
|
||||||
}
|
|
||||||
// No else cannot read first line (ignore this kind of error)
|
|
||||||
line = "";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
if (nbDocumentedModules>0)
|
|
||||||
{
|
|
||||||
return 0;
|
|
||||||
}
|
|
||||||
else
|
|
||||||
{
|
|
||||||
return 1;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
//----------------------------------------------------------------------------
|
|
||||||
static void trim(std::string& s)
|
|
||||||
{
|
|
||||||
std::string::size_type pos = s.find_last_not_of(' ');
|
|
||||||
if(pos != std::string::npos)
|
|
||||||
{
|
|
||||||
s.erase(pos + 1);
|
|
||||||
pos = s.find_first_not_of(' ');
|
|
||||||
if(pos != std::string::npos) s.erase(0, pos);
|
|
||||||
}
|
|
||||||
else
|
|
||||||
{
|
|
||||||
s.erase(s.begin(), s.end());
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
int cmDocumentation::GetStructuredDocFromFile(
|
|
||||||
const char* fname,
|
|
||||||
std::vector<cmDocumentationEntry>& commands,
|
|
||||||
cmake* cm)
|
|
||||||
{
|
|
||||||
enum sdoce {
|
|
||||||
SDOC_NONE, SDOC_MODULE, SDOC_MACRO, SDOC_FUNCTION, SDOC_VARIABLE,
|
|
||||||
SDOC_SECTION,
|
|
||||||
SDOC_UNKNOWN};
|
|
||||||
int nbDocItemFound = 0;
|
|
||||||
int docCtxIdx = 0;
|
|
||||||
std::vector<int> docContextStack(60);
|
|
||||||
docContextStack[docCtxIdx]=SDOC_NONE;
|
|
||||||
cmDocumentationEntry e;
|
|
||||||
std::ifstream fin(fname);
|
|
||||||
if(!fin)
|
|
||||||
{
|
|
||||||
return nbDocItemFound;
|
|
||||||
}
|
|
||||||
std::string section;
|
|
||||||
std::string name;
|
|
||||||
std::string full;
|
|
||||||
std::string brief;
|
|
||||||
std::string line;
|
|
||||||
bool newCtx = false; /* we've just entered ##<beginkey> context */
|
|
||||||
bool inBrief = false; /* we are currently parsing brief desc. */
|
|
||||||
bool inFullFirstParagraph = false; /* we are currently parsing full
|
|
||||||
desc. first paragraph */
|
|
||||||
brief = "";
|
|
||||||
full = "";
|
|
||||||
bool newParagraph = true;
|
|
||||||
while ( fin && cmSystemTools::GetLineFromStream(fin, line) )
|
|
||||||
{
|
|
||||||
if(line.size() && line[0] == '#')
|
|
||||||
{
|
|
||||||
/* handle structured doc context */
|
|
||||||
if ((line.size()>=2) && line[1]=='#')
|
|
||||||
{
|
|
||||||
/* markup word is following '##' stopping at first space
|
|
||||||
* Some markup word like 'section' may have more characters
|
|
||||||
* following but we don't handle those here.
|
|
||||||
*/
|
|
||||||
std::string mkword = line.substr(2,line.find(' ',2)-2);
|
|
||||||
if (mkword=="macro")
|
|
||||||
{
|
|
||||||
docCtxIdx++;
|
|
||||||
docContextStack[docCtxIdx]=SDOC_MACRO;
|
|
||||||
newCtx = true;
|
|
||||||
}
|
|
||||||
else if (mkword=="variable")
|
|
||||||
{
|
|
||||||
docCtxIdx++;
|
|
||||||
docContextStack[docCtxIdx]=SDOC_VARIABLE;
|
|
||||||
newCtx = true;
|
|
||||||
}
|
|
||||||
else if (mkword=="function")
|
|
||||||
{
|
|
||||||
docCtxIdx++;
|
|
||||||
docContextStack[docCtxIdx]=SDOC_FUNCTION;
|
|
||||||
newCtx = true;
|
|
||||||
}
|
|
||||||
else if (mkword=="module")
|
|
||||||
{
|
|
||||||
docCtxIdx++;
|
|
||||||
docContextStack[docCtxIdx]=SDOC_MODULE;
|
|
||||||
newCtx = true;
|
|
||||||
}
|
|
||||||
else if (mkword=="section")
|
|
||||||
{
|
|
||||||
docCtxIdx++;
|
|
||||||
docContextStack[docCtxIdx]=SDOC_SECTION;
|
|
||||||
// 10 is the size of '##section' + 1
|
|
||||||
section = line.substr(10,std::string::npos);
|
|
||||||
/* drop the rest of the line */
|
|
||||||
line = "";
|
|
||||||
newCtx = true;
|
|
||||||
}
|
|
||||||
else if (mkword.substr(0,3)=="end")
|
|
||||||
{
|
|
||||||
switch (docContextStack[docCtxIdx]) {
|
|
||||||
case SDOC_MACRO:
|
|
||||||
/* for now MACRO and FUNCTION are handled in the same way */
|
|
||||||
case SDOC_FUNCTION:
|
|
||||||
commands.push_back(cmDocumentationEntry(name.c_str(),
|
|
||||||
brief.c_str(),full.c_str()));
|
|
||||||
break;
|
|
||||||
case SDOC_VARIABLE:
|
|
||||||
this->addAutomaticVariableSections(section);
|
|
||||||
cm->DefineProperty
|
|
||||||
(name.c_str(), cmProperty::VARIABLE,
|
|
||||||
brief.c_str(),
|
|
||||||
full.c_str(),false,
|
|
||||||
section.c_str());
|
|
||||||
break;
|
|
||||||
case SDOC_MODULE:
|
|
||||||
/* not implemented */
|
|
||||||
break;
|
|
||||||
case SDOC_SECTION:
|
|
||||||
/* not implemented */
|
|
||||||
break;
|
|
||||||
default:
|
|
||||||
/* ignore other cases */
|
|
||||||
break;
|
|
||||||
}
|
|
||||||
docCtxIdx--;
|
|
||||||
newCtx = false;
|
|
||||||
++nbDocItemFound;
|
|
||||||
}
|
|
||||||
else
|
|
||||||
{
|
|
||||||
// error out unhandled context
|
|
||||||
return nbDocItemFound;
|
|
||||||
}
|
|
||||||
/* context is set go to next doc line */
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
// Now parse the text attached to the context
|
|
||||||
|
|
||||||
// The first line after the context mark-up contains::
|
|
||||||
// name - brief until. (brief is dot terminated or
|
|
||||||
// followed by a blank line)
|
|
||||||
if (newCtx)
|
|
||||||
{
|
|
||||||
// no brief (for easy variable definition)
|
|
||||||
if (line.find("-")==std::string::npos)
|
|
||||||
{
|
|
||||||
name = line.substr(1,std::string::npos);
|
|
||||||
trim(name);
|
|
||||||
brief = "";
|
|
||||||
inBrief = false;
|
|
||||||
full = "";
|
|
||||||
}
|
|
||||||
// here we have a name and brief beginning
|
|
||||||
else
|
|
||||||
{
|
|
||||||
name = line.substr(1,line.find("-")-1);
|
|
||||||
trim(name);
|
|
||||||
// we are parsing the brief context
|
|
||||||
brief = line.substr(line.find("-")+1,std::string::npos);
|
|
||||||
trim(brief);
|
|
||||||
// Brief may already be terminated on the first line
|
|
||||||
if (brief.find('.')!=std::string::npos)
|
|
||||||
{
|
|
||||||
inBrief = false;
|
|
||||||
full = brief.substr(brief.find('.')+1,std::string::npos);
|
|
||||||
trim(full);
|
|
||||||
inFullFirstParagraph = true;
|
|
||||||
brief = brief.substr(0,brief.find('.'));
|
|
||||||
}
|
|
||||||
// brief is continued on following lines
|
|
||||||
else
|
|
||||||
{
|
|
||||||
inBrief = true;
|
|
||||||
full = "";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
newCtx = false;
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
// blank line
|
|
||||||
if(line.size() <= 2)
|
|
||||||
{
|
|
||||||
if (inBrief) {
|
|
||||||
inBrief = false;
|
|
||||||
full = "";
|
|
||||||
} else {
|
|
||||||
if (full.length()>0)
|
|
||||||
{
|
|
||||||
full += "\n";
|
|
||||||
}
|
|
||||||
// the first paragraph of full has ended
|
|
||||||
inFullFirstParagraph = false;
|
|
||||||
}
|
|
||||||
newParagraph = true;
|
|
||||||
}
|
|
||||||
// brief is terminated by '.'
|
|
||||||
else if (inBrief && (line.find('.')!=std::string::npos))
|
|
||||||
{
|
|
||||||
/* the brief just ended */
|
|
||||||
inBrief = false;
|
|
||||||
std::string endBrief = line.substr(1,line.find('.'));
|
|
||||||
trim(endBrief);
|
|
||||||
trim(brief);
|
|
||||||
brief += " " + endBrief;
|
|
||||||
full += line.substr(line.find('.')+1,std::string::npos);
|
|
||||||
trim(full);
|
|
||||||
inFullFirstParagraph = true;
|
|
||||||
}
|
|
||||||
// we handle full text or multi-line brief.
|
|
||||||
else
|
|
||||||
{
|
|
||||||
std::string* text;
|
|
||||||
if (inBrief)
|
|
||||||
{
|
|
||||||
text = &brief;
|
|
||||||
}
|
|
||||||
else
|
|
||||||
{
|
|
||||||
text = &full;
|
|
||||||
}
|
|
||||||
// two spaces
|
|
||||||
if(line[1] == ' ' && line[2] == ' ')
|
|
||||||
{
|
|
||||||
// there is no "full first paragraph at all."
|
|
||||||
if (line[3] == ' ')
|
|
||||||
{
|
|
||||||
inFullFirstParagraph = false;
|
|
||||||
}
|
|
||||||
|
|
||||||
if(!newParagraph && !inFullFirstParagraph)
|
|
||||||
{
|
|
||||||
*text += "\n";
|
|
||||||
newParagraph = true;
|
|
||||||
}
|
|
||||||
// Skip #, and leave space for pre-formatted
|
|
||||||
if (inFullFirstParagraph)
|
|
||||||
{
|
|
||||||
std::string temp = line.c_str()+1;
|
|
||||||
trim(temp);
|
|
||||||
*text += " " + temp;
|
|
||||||
}
|
|
||||||
else
|
|
||||||
{
|
|
||||||
*text += line.c_str()+1;
|
|
||||||
*text += "\n";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
else if(line[1] == ' ')
|
|
||||||
{
|
|
||||||
if(!newParagraph)
|
|
||||||
{
|
|
||||||
*text += " ";
|
|
||||||
}
|
|
||||||
newParagraph = false;
|
|
||||||
// skip # and space
|
|
||||||
*text += line.c_str()+2;
|
|
||||||
}
|
|
||||||
else
|
|
||||||
{
|
|
||||||
if(!newParagraph)
|
|
||||||
{
|
|
||||||
*text += " ";
|
|
||||||
}
|
|
||||||
newParagraph = false;
|
|
||||||
// skip #
|
|
||||||
*text += line.c_str()+1;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
/* next line is not the first context line */
|
|
||||||
newCtx = false;
|
|
||||||
}
|
|
||||||
return nbDocItemFound;
|
|
||||||
}
|
|
||||||
|
|
||||||
//----------------------------------------------------------------------------
|
//----------------------------------------------------------------------------
|
||||||
bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
|
bool cmDocumentation::CheckOptions(int argc, const char* const* argv,
|
||||||
|
|||||||
@ -151,44 +151,6 @@ public:
|
|||||||
/** Add automatic variables sections */
|
/** Add automatic variables sections */
|
||||||
void addAutomaticVariableSections(const std::string& section);
|
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] docModuleList 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] cm the cmake object instance to which variable
|
|
||||||
* documentation will be attached
|
|
||||||
* (using @see cmake::DefineProperty)
|
|
||||||
* @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:
|
private:
|
||||||
void SetForm(Form f, int manSection);
|
void SetForm(Form f, int manSection);
|
||||||
void SetDocName(const char* docname);
|
void SetDocName(const char* docname);
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user