Commit 0d0fec15 authored by Brad King's avatar Brad King
Browse files

Drop CPack module documentation markup extraction

This will be replaced by alternative markup later.
parent 946f0efb
......@@ -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);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment