Add reStructuredText (RST) documentation formatter
Temporarily add a RST formatter to convert builtin documentation to .rst source files. This will be removed shortly after we use it to convert documentation. Teach the RST formatter to: * Output preformatted blocks as reStructuredText "::" literal blocks. * Output option lists as bullet lists with option names enclosed in reStructuredText ``literal`` quoting. * Output individual documentation objects (commands, variables, etc.) in separate .rst files organized in directories by type. Replace references to cmVersion::GetCMakeVersion() in builtin documentation with the literal placeholder "|release|" that will be defined as a substitution later.
This commit is contained in:
parent
0d0fec1524
commit
f85405f551
|
@ -162,6 +162,7 @@ set(SRCS
|
|||
cmDocumentationFormatterHTML.cxx
|
||||
cmDocumentationFormatterDocbook.cxx
|
||||
cmDocumentationFormatterMan.cxx
|
||||
cmDocumentationFormatterRST.cxx
|
||||
cmDocumentationFormatterText.cxx
|
||||
cmDocumentationFormatterUsage.cxx
|
||||
cmDocumentationSection.cxx
|
||||
|
|
|
@ -654,6 +654,11 @@ cmDocumentation::Form cmDocumentation::GetFormFromFilename(
|
|||
return cmDocumentation::ManForm;
|
||||
}
|
||||
|
||||
if (ext == ".RST")
|
||||
{
|
||||
return cmDocumentation::RSTForm;
|
||||
}
|
||||
|
||||
return cmDocumentation::TextForm;
|
||||
}
|
||||
|
||||
|
@ -1580,6 +1585,9 @@ void cmDocumentation::SetForm(Form f, int manSection)
|
|||
this->ManFormatter.SetManSection(manSection);
|
||||
this->CurrentFormatter = &this->ManFormatter;
|
||||
break;
|
||||
case RSTForm:
|
||||
this->CurrentFormatter = &this->RSTFormatter;
|
||||
break;
|
||||
case TextForm:
|
||||
this->CurrentFormatter = &this->TextFormatter;
|
||||
break;
|
||||
|
|
|
@ -18,6 +18,7 @@
|
|||
#include "cmDocumentationFormatterHTML.h"
|
||||
#include "cmDocumentationFormatterDocbook.h"
|
||||
#include "cmDocumentationFormatterMan.h"
|
||||
#include "cmDocumentationFormatterRST.h"
|
||||
#include "cmDocumentationFormatterText.h"
|
||||
#include "cmDocumentationFormatterUsage.h"
|
||||
#include "cmDocumentationSection.h"
|
||||
|
@ -222,6 +223,7 @@ private:
|
|||
cmDocumentationFormatterHTML HTMLFormatter;
|
||||
cmDocumentationFormatterDocbook DocbookFormatter;
|
||||
cmDocumentationFormatterMan ManFormatter;
|
||||
cmDocumentationFormatterRST RSTFormatter;
|
||||
cmDocumentationFormatterText TextFormatter;
|
||||
cmDocumentationFormatterUsage UsageFormatter;
|
||||
|
||||
|
|
|
@ -81,7 +81,7 @@ cmDocumentationFormatter::ComputeSectionLinkPrefix(std::string const& name)
|
|||
{
|
||||
if(name.find("Global") != name.npos)
|
||||
{
|
||||
return "prop_global";
|
||||
return "prop_gbl";
|
||||
}
|
||||
else if(name.find("Direct") != name.npos)
|
||||
{
|
||||
|
@ -99,10 +99,34 @@ cmDocumentationFormatter::ComputeSectionLinkPrefix(std::string const& name)
|
|||
{
|
||||
return "prop_sf";
|
||||
}
|
||||
else if(name.find("Cache") != name.npos)
|
||||
{
|
||||
return "prop_cache";
|
||||
}
|
||||
return "property";
|
||||
}
|
||||
else if(name.find("Variable") != name.npos)
|
||||
{
|
||||
if(name.find("Information") != name.npos)
|
||||
{
|
||||
return "var_info";
|
||||
}
|
||||
else if(name.find("Behavior") != name.npos)
|
||||
{
|
||||
return "var_cmake";
|
||||
}
|
||||
else if(name.find("Describe") != name.npos)
|
||||
{
|
||||
return "var_sys";
|
||||
}
|
||||
else if(name.find("Control") != name.npos)
|
||||
{
|
||||
return "var_build";
|
||||
}
|
||||
else if(name.find("Languages") != name.npos)
|
||||
{
|
||||
return "var_lang";
|
||||
}
|
||||
return "variable";
|
||||
}
|
||||
else if(name.find("Polic") != name.npos)
|
||||
|
@ -128,7 +152,7 @@ cmDocumentationFormatter::ComputeSectionLinkPrefix(std::string const& name)
|
|||
}
|
||||
else if(name.find("Generators") != name.npos)
|
||||
{
|
||||
return "gen";
|
||||
return "generator";
|
||||
}
|
||||
else if(name.find("Options") != name.npos)
|
||||
{
|
||||
|
|
|
@ -31,7 +31,7 @@ public:
|
|||
CompatCommands, Copyright, Version, Policies, SinglePolicy };
|
||||
|
||||
/** Forms of documentation output. */
|
||||
enum Form { TextForm, HTMLForm, ManForm, UsageForm, DocbookForm };
|
||||
enum Form { TextForm, HTMLForm, RSTForm, ManForm, UsageForm, DocbookForm };
|
||||
};
|
||||
|
||||
class cmDocumentationSection;
|
||||
|
|
|
@ -0,0 +1,107 @@
|
|||
/*============================================================================
|
||||
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.
|
||||
============================================================================*/
|
||||
#include "cmDocumentationFormatterRST.h"
|
||||
#include "cmDocumentationSection.h"
|
||||
#include "cmVersion.h"
|
||||
|
||||
#include "cmSystemTools.h"
|
||||
|
||||
cmDocumentationFormatterRST::cmDocumentationFormatterRST()
|
||||
:cmDocumentationFormatterText()
|
||||
{
|
||||
}
|
||||
|
||||
static std::string rstFileName(std::string fn)
|
||||
{
|
||||
cmSystemTools::ReplaceString(fn, "<", "");
|
||||
cmSystemTools::ReplaceString(fn, ">", "");
|
||||
return fn;
|
||||
}
|
||||
|
||||
void cmDocumentationFormatterRST
|
||||
::PrintSection(std::ostream& os,
|
||||
const cmDocumentationSection §ion,
|
||||
const char* name)
|
||||
{
|
||||
std::string prefix = this->ComputeSectionLinkPrefix(name);
|
||||
std::vector<cmDocumentationEntry> const& entries = section.GetEntries();
|
||||
this->TextWidth = 70;
|
||||
|
||||
for(std::vector<cmDocumentationEntry>::const_iterator op = entries.begin();
|
||||
op != entries.end();)
|
||||
{
|
||||
if(op->Name.size())
|
||||
{
|
||||
for(;op != entries.end() && op->Name.size(); ++op)
|
||||
{
|
||||
if(prefix == "opt" || prefix == "see")
|
||||
{
|
||||
os << "\n";
|
||||
os << "* ``" << op->Name << "``: " << op->Brief << "\n";
|
||||
this->TextIndent = " ";
|
||||
if(op->Full.size())
|
||||
{
|
||||
os << "\n";
|
||||
this->PrintFormatted(os, op->Full.c_str());
|
||||
}
|
||||
this->TextIndent = "";
|
||||
}
|
||||
else
|
||||
{
|
||||
cmSystemTools::MakeDirectory(prefix.c_str());
|
||||
std::string fname = prefix + "/" + rstFileName(op->Name) + ".rst";
|
||||
if(cmSystemTools::FileExists(fname.c_str()))
|
||||
{
|
||||
cmSystemTools::Error("Duplicate file name: ", fname.c_str());
|
||||
continue;
|
||||
}
|
||||
std::ofstream of(fname.c_str());
|
||||
of << op->Name << "\n";
|
||||
for(size_t i = 0; i < op->Name.size(); ++i)
|
||||
{
|
||||
of << "-";
|
||||
}
|
||||
of << "\n\n" << op->Brief << "\n";
|
||||
if(op->Full.size())
|
||||
{
|
||||
of << "\n";
|
||||
this->PrintFormatted(of, op->Full.c_str());
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
this->PrintFormatted(os, op->Brief.c_str());
|
||||
os << "\n";
|
||||
++op;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
void cmDocumentationFormatterRST::PrintPreformatted(std::ostream& os,
|
||||
const char* text)
|
||||
{
|
||||
os << this->TextIndent << "::\n\n";
|
||||
bool newline = true;
|
||||
for(const char* c = text; *c; ++c)
|
||||
{
|
||||
if (newline)
|
||||
{
|
||||
os << this->TextIndent;
|
||||
newline = false;
|
||||
}
|
||||
os << *c;
|
||||
newline = (*c == '\n');
|
||||
}
|
||||
os << "\n";
|
||||
}
|
|
@ -0,0 +1,34 @@
|
|||
/*============================================================================
|
||||
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 _cmDocumentationFormatterRST_h
|
||||
#define _cmDocumentationFormatterRST_h
|
||||
|
||||
#include "cmStandardIncludes.h"
|
||||
|
||||
#include "cmDocumentationFormatterText.h"
|
||||
|
||||
/** Class to print the documentation as reStructuredText. */
|
||||
class cmDocumentationFormatterRST : public cmDocumentationFormatterText
|
||||
{
|
||||
public:
|
||||
cmDocumentationFormatterRST();
|
||||
|
||||
virtual cmDocumentationEnums::Form GetForm() const
|
||||
{ return cmDocumentationEnums::RSTForm;}
|
||||
|
||||
virtual void PrintSection(std::ostream& os,
|
||||
const cmDocumentationSection& section,
|
||||
const char* name);
|
||||
virtual void PrintPreformatted(std::ostream& os, const char* text);
|
||||
};
|
||||
|
||||
#endif
|
|
@ -949,7 +949,7 @@ void cmPolicies::GetDocumentation(std::vector<cmDocumentationEntry>& v)
|
|||
if(i->first != cmPolicies::CMP0000)
|
||||
{
|
||||
full << " "
|
||||
<< "CMake version " << cmVersion::GetCMakeVersion() << " ";
|
||||
<< "CMake version |release| ";
|
||||
// add in some more text here based on status
|
||||
switch (i->second->Status)
|
||||
{
|
||||
|
|
Loading…
Reference in New Issue