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::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;
|
||||
cminst.GetPropertiesDocumentation(propDocs);
|
||||
doc.SetSections(propDocs);
|
||||
|
|
|
|||
|
|
@ -502,8 +502,6 @@ bool cmDocumentation::CreateSingleModule(const char* fname,
|
|||
{
|
||||
if(line.size() && line[0] == '#')
|
||||
{
|
||||
/* line beginnings with ## are mark-up ignore them */
|
||||
if (line.size()>=2 && line[1] == '#') continue;
|
||||
// blank line
|
||||
if(line.size() <= 2)
|
||||
{
|
||||
|
|
@ -750,331 +748,6 @@ void cmDocumentation::addAutomaticVariableSections(const std::string& 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,
|
||||
|
|
|
|||
|
|
@ -151,44 +151,6 @@ public:
|
|||
/** 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] 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:
|
||||
void SetForm(Form f, int manSection);
|
||||
void SetDocName(const char* docname);
|
||||
|
|
|
|||
Loading…
Reference in New Issue