qdoc: Prepare QDoc for the new style on qt.io

The new template and CSS have some requirements that need changes
in the generated .html:

    - Generate a new div 'sidebar' and place the TOC (if one
      exists) inside it, allowing the template to extend the
      sidebar contents dynamically. Do this for all pages
      except index.html.

    - Change the DOCTYPE declaration to be html5-compliant

    - Replace <tt> tags with <code> to be html5-compliant

    - Add a new config variable HTML.prologue - this allows
      the template to insert custom html into beginning of
      the page, before the page title but after any navigation
      or table-of-contents items.

    - Wrap tables inside <div> elements. This allows for
      better-working CSS design for small-screen devices.

    - Write out extra parameters first when outputting
      function synopsis to have better styling.

    - Inject zero-width-space characters into function
      names to allow the browser break up long function
      signatures in a nice manner.

    - Edit the CSS for the offline style to adapt to
      above changes.

Task-number: QTBUG-42086
Change-Id: I3075cdc11bcb07a66150388519263fd721c8002b
Reviewed-by: Martin Smith <martin.smith@digia.com>
This commit is contained in:
Topi Reinio 2014-10-21 10:22:45 +02:00 committed by Jani Heikkinen
parent 9d38dbde76
commit 1ad78f5f29
4 changed files with 90 additions and 53 deletions

View File

@ -359,7 +359,9 @@ h3.fn, span.fn {
margin: 0px;
margin-top: 45px;
}
h3.fn code {
float: right;
}
h3.fn:target {
background-color: #F6F6D6;
}
@ -705,8 +707,21 @@ Landing page
float: left;
}
.icons1of3 h2 {
.icons1of3 h2, .doc-column h2 {
font-size: 15px;
margin: 0px;
padding: 0px;
}
div.multi-column {
position: relative;
}
div.multi-column div {
display: -moz-inline-box;
display: inline-block;
vertical-align: top;
margin-top: 1em;
margin-right: 4em;
width: 24em;
}

View File

@ -136,7 +136,7 @@ QString CppCodeMarker::markedUpSynopsis(const Node *node,
if ((style == Detailed) && !node->parent()->name().isEmpty() &&
(node->type() != Node::Property) && !node->isQmlNode())
name.prepend(taggedNode(node->parent()) + "::");
name.prepend(taggedNode(node->parent()) + "::&#8203;");
switch (node->type()) {
case Node::Namespace:
@ -212,7 +212,7 @@ QString CppCodeMarker::markedUpSynopsis(const Node *node,
bracketed += "slot";
}
if (!bracketed.isEmpty())
extra += " [" + bracketed.join(' ') + QLatin1Char(']');
extra += QLatin1Char('[') + bracketed.join(' ') + QStringLiteral("] ");
}
break;
case Node::Enum:
@ -297,7 +297,7 @@ QString CppCodeMarker::markedUpSynopsis(const Node *node,
extra.prepend("<@extra>");
extra.append("</@extra>");
}
return synopsis + extra;
return extra + synopsis;
}
/*!

View File

@ -121,7 +121,7 @@ void HtmlGenerator::initializeGenerator(const Config &config)
{ ATOM_FORMATTING_PARAMETER, "<i>", "</i>" },
{ ATOM_FORMATTING_SUBSCRIPT, "<sub>", "</sub>" },
{ ATOM_FORMATTING_SUPERSCRIPT, "<sup>", "</sup>" },
{ ATOM_FORMATTING_TELETYPE, "<tt>", "</tt>" },
{ ATOM_FORMATTING_TELETYPE, "<code>", "</code>" }, // <tt> tag is not supported in HTML5
{ ATOM_FORMATTING_UICONTROL, "<b>", "</b>" },
{ ATOM_FORMATTING_UNDERLINE, "<u>", "</u>" },
{ 0, 0, 0 }
@ -149,6 +149,10 @@ void HtmlGenerator::initializeGenerator(const Config &config)
postPostHeader = config.getString(HtmlGenerator::format() +
Config::dot +
HTMLGENERATOR_POSTPOSTHEADER);
prologue = config.getString(HtmlGenerator::format() +
Config::dot +
HTMLGENERATOR_PROLOGUE);
footer = config.getString(HtmlGenerator::format() +
Config::dot +
HTMLGENERATOR_FOOTER);
@ -845,7 +849,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
out() << "<dl>\n";
}
else if (atom->string() == ATOM_LIST_VALUE) {
out() << "<table class=\"valuelist\">";
out() << "<div class=\"table\"><table class=\"valuelist\">";
threeColumnEnumValueTable_ = isThreeColumnEnumValueTable(atom);
if (threeColumnEnumValueTable_) {
if (++numTableRows_ % 2 == 1)
@ -897,7 +901,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
// ### Trenton
QString t= protectEnc(plainCode(marker->markedUpEnumValue(atom->next()->string(),relative)));
out() << "<tr><td class=\"topAlign\"><tt>" << t << "</tt>";
out() << "<tr><td class=\"topAlign\"><code>" << t << "</code>";
if (relative->type() == Node::Enum) {
out() << "</td><td class=\"topAlign\">";
@ -907,7 +911,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
if (itemValue.isEmpty())
out() << '?';
else
out() << "<tt>" << protectEnc(itemValue) << "</tt>";
out() << "<code>" << protectEnc(itemValue) << "</code>";
}
skipAhead = 1;
}
@ -952,7 +956,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
out() << "</dl>\n";
}
else if (atom->string() == ATOM_LIST_VALUE) {
out() << "</table>\n";
out() << "</table></div>\n";
}
else {
out() << "</ol>\n";
@ -1040,7 +1044,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
else if (p2.contains("%"))
width = p2;
}
out() << "<table class=\"" << attr << "\"";
out() << "<div class=\"table\"><table class=\"" << attr << "\"";
if (!width.isEmpty())
out() << " width=\"" << width << "\"";
out() << ">\n ";
@ -1048,7 +1052,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
}
break;
case Atom::TableRight:
out() << "</table>\n";
out() << "</table></div>\n";
break;
case Atom::TableHeaderLeft:
out() << "<thead><tr class=\"qt-style\">";
@ -1456,8 +1460,7 @@ void HtmlGenerator::generateDocNode(DocNode* dn, CodeMarker* marker)
Generate the TOC for the new doc format.
Don't generate a TOC for the home page.
*/
if ((dn->name() != QString("index.html")) &&
(dn->name() != QString("qtexamplesandtutorials.html")))
if ((dn->name() != QStringLiteral("index.html")))
generateTableOfContents(dn,marker,0);
generateTitle(fullTitle,
@ -1707,8 +1710,8 @@ void HtmlGenerator::generateHeader(const QString& title,
#else
out() << QString("<?xml version=\"1.0\"?>\n");
#endif
out() << "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n";
out() << QString("<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"%1\" lang=\"%1\">\n").arg(naturalLanguage);
out() << "<!DOCTYPE html>\n";
out() << QString("<html lang=\"%1\">\n").arg(naturalLanguage);
out() << "<head>\n";
out() << " <meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\" />\n";
if (node && !node->doc().location().isEmpty())
@ -1775,7 +1778,8 @@ void HtmlGenerator::generateHeader(const QString& title,
out() << QString(postHeader).replace("\\" + COMMAND_VERSION, qdb_->version());
generateNavigationBar(title,node,marker);
out() << "<li id=\"buildversion\">\n" << buildversion << "</li>\n";
if (!buildversion.isEmpty())
out() << "<li id=\"buildversion\">" << buildversion << "</li>\n";
out() << QString(postPostHeader).replace("\\" + COMMAND_VERSION, qdb_->version());
navigationLinks.clear();
@ -1849,6 +1853,7 @@ void HtmlGenerator::generateTitle(const QString& title,
const Node *relative,
CodeMarker *marker)
{
out() << QString(prologue).replace("\\" + COMMAND_VERSION, qdb_->version());
if (!title.isEmpty())
out() << "<h1 class=\"title\">" << protectEnc(title) << "</h1>\n";
if (!subTitle.isEmpty()) {
@ -1993,7 +1998,7 @@ void HtmlGenerator::generateRequisites(InnerNode *inner, CodeMarker *marker)
if (!requisites.isEmpty()) {
//generate the table
out() << "<table class=\"alignedsummary\">\n";
out() << "<div class=\"table\"><table class=\"alignedsummary\">\n";
QStringList::ConstIterator i;
for (i = requisiteorder.begin(); i != requisiteorder.constEnd(); ++i) {
@ -2011,7 +2016,7 @@ void HtmlGenerator::generateRequisites(InnerNode *inner, CodeMarker *marker)
out() << "</td></tr>";
}
}
out() << "</table>";
out() << "</table></div>";
}
}
@ -2112,7 +2117,7 @@ void HtmlGenerator::generateQmlRequisites(QmlClassNode *qcn, CodeMarker *marker)
if (!requisites.isEmpty()) {
//generate the table
out() << "<table class=\"alignedsummary\">\n";
out() << "<div class=\"table\"><table class=\"alignedsummary\">\n";
QStringList::ConstIterator i;
for (i = requisiteorder.begin(); i != requisiteorder.constEnd(); ++i) {
@ -2130,7 +2135,7 @@ void HtmlGenerator::generateQmlRequisites(QmlClassNode *qcn, CodeMarker *marker)
out() << "</td></tr>";
}
}
out() << "</table>";
out() << "</table></div>";
}
}
@ -2176,12 +2181,10 @@ void HtmlGenerator::generateTableOfContents(const Node *node,
QList<Atom*> toc;
if (node->doc().hasTableOfContents())
toc = node->doc().tableOfContents();
if (toc.isEmpty() && !sections && !node->isModule())
return;
//turn off table of contents if HTML.tocdepth is set to 0
if (tocDepth == 0)
if (tocDepth == 0 || (toc.isEmpty() && !sections && !node->isModule())) {
generateSidebar();
return;
}
QStringList sectionNumber;
int detailsBase = 0;
@ -2190,6 +2193,7 @@ void HtmlGenerator::generateTableOfContents(const Node *node,
inContents_ = true;
inLink_ = true;
out() << "<div class=\"sidebar\">\n";
out() << "<div class=\"toc\">\n";
out() << "<h3><a name=\"toc\">Contents</a></h3>\n";
sectionNumber.append("1");
@ -2287,10 +2291,21 @@ void HtmlGenerator::generateTableOfContents(const Node *node,
}
out() << "</ul>\n";
out() << "</div>\n";
out() << "<div class=\"sidebar-content\" id=\"sidebar-content\"></div>";
out() << "</div>\n";
inContents_ = false;
inLink_ = false;
}
/*!
Outputs a placeholder div where the style can add customized sidebar content.
*/
void HtmlGenerator::generateSidebar() {
out() << "<div class=\"sidebar\">";
out() << "<div class=\"sidebar-content\" id=\"sidebar-content\"></div>";
out() << "</div>\n";
}
QString HtmlGenerator::generateListOfAllMemberFile(const InnerNode *inner,
CodeMarker *marker)
{
@ -2307,6 +2322,7 @@ QString HtmlGenerator::generateListOfAllMemberFile(const InnerNode *inner,
beginSubPage(inner, fileName);
QString title = "List of All Members for " + inner->name();
generateHeader(title, inner, marker);
generateSidebar();
generateTitle(title, Text(), SmallSubTitle, inner, marker);
out() << "<p>This is the complete list of members for ";
generateFullName(inner, 0);
@ -2338,6 +2354,7 @@ QString HtmlGenerator::generateAllQmlMembersFile(QmlClassNode* qml_cn, CodeMarke
beginSubPage(qml_cn, fileName);
QString title = "List of All Members for " + qml_cn->name();
generateHeader(title, qml_cn, marker);
generateSidebar();
generateTitle(title, Text(), SmallSubTitle, qml_cn, marker);
out() << "<p>This is the complete list of members for ";
generateFullName(qml_cn, 0);
@ -2422,6 +2439,7 @@ QString HtmlGenerator::generateLowStatusMemberFile(InnerNode *inner,
beginSubPage(inner, fileName);
generateHeader(title, inner, marker);
generateSidebar();
generateTitle(title, Text(), SmallSubTitle, inner, marker);
if (status == CodeMarker::Compat) {
@ -2498,6 +2516,7 @@ QString HtmlGenerator::generateQmlMemberFile(QmlClassNode* qcn,
beginSubPage(qcn, fileName);
generateHeader(title, qcn, marker);
generateSidebar();
generateTitle(title, Text(), SmallSubTitle, qcn, marker);
out() << "<p><b>The following members of QML type "
@ -2615,7 +2634,7 @@ void HtmlGenerator::generateAnnotatedList(const Node *relative,
}
if (allInternal)
return;
out() << "<table class=\"annotated\">\n";
out() << "<div class=\"table\"><table class=\"annotated\">\n";
int row = 0;
NodeList nodes = nm.values();
foreach (const Node* node, nodes) {
@ -2651,7 +2670,7 @@ void HtmlGenerator::generateAnnotatedList(const Node *relative,
}
out() << "</tr>\n";
}
out() << "</table>\n";
out() << "</table></div>\n";
}
/*!
@ -2902,8 +2921,8 @@ void HtmlGenerator::generateQmlItem(const Node *node,
if (summary)
marked.replace("@name>", "b>");
marked.replace("<@extra>", "<tt>");
marked.replace("</@extra>", "</tt>");
marked.replace("<@extra>", "<code>");
marked.replace("</@extra>", "</code>");
if (summary) {
marked.remove("<@type>");
@ -3027,11 +3046,11 @@ void HtmlGenerator::generateSection(const NodeList& nl,
alignNames = false;
}
if (alignNames) {
out() << "<table class=\"alignedsummary\">\n";
out() << "<div class=\"table\"><table class=\"alignedsummary\">\n";
}
else {
if (twoColumn)
out() << "<table class=\"propsummary\">\n"
out() << "<div class=\"table\"><table class=\"propsummary\">\n"
<< "<tr><td class=\"topAlign\">";
out() << "<ul>\n";
}
@ -3062,11 +3081,11 @@ void HtmlGenerator::generateSection(const NodeList& nl,
++m;
}
if (alignNames)
out() << "</table>\n";
out() << "</table></div>\n";
else {
out() << "</ul>\n";
if (twoColumn)
out() << "</td></tr>\n</table>\n";
out() << "</td></tr>\n</table></div>\n";
}
}
}
@ -3088,11 +3107,11 @@ void HtmlGenerator::generateSectionList(const Section& section,
alignNames = false;
}
if (alignNames) {
out() << "<table class=\"alignedsummary\">\n";
out() << "<div class=\"table\"><table class=\"alignedsummary\">\n";
}
else {
if (twoColumn)
out() << "<table class=\"propsummary\">\n"
out() << "<div class=\"table\"><table class=\"propsummary\">\n"
<< "<tr><td class=\"topAlign\">";
out() << "<ul>\n";
}
@ -3128,11 +3147,11 @@ void HtmlGenerator::generateSectionList(const Section& section,
++m;
}
if (alignNames)
out() << "</table>\n";
out() << "</table></div>\n";
else {
out() << "</ul>\n";
if (twoColumn)
out() << "</td></tr>\n</table>\n";
out() << "</td></tr>\n</table></div>\n";
}
}
@ -3196,8 +3215,8 @@ void HtmlGenerator::generateSynopsis(const Node *node,
extraRegExp.setMinimal(true);
marked.remove(extraRegExp);
} else {
marked.replace("<@extra>", "<tt>");
marked.replace("</@extra>", "</tt>");
marked.replace("<@extra>", "<code>");
marked.replace("</@extra>", "</code>");
}
if (style != CodeMarker::Detailed) {
@ -4058,7 +4077,7 @@ void HtmlGenerator::generateDetailedQmlMember(Node *node,
const QmlPropertyGroupNode* qpgn = static_cast<const QmlPropertyGroupNode*>(node);
NodeList::ConstIterator p = qpgn->childNodes().constBegin();
out() << "<div class=\"qmlproto\">";
out() << "<table class=\"qmlname\">";
out() << "<div class=\"table\"><table class=\"qmlname\">";
QString heading = qpgn->name() + " group";
out() << "<tr valign=\"top\" class=\"even\" id=\"" << nodeRef << "\">";
@ -4083,13 +4102,13 @@ void HtmlGenerator::generateDetailedQmlMember(Node *node,
}
++p;
}
out() << "</table>";
out() << "</table></div>";
out() << "</div>";
}
else if (node->type() == Node::QmlProperty) {
qpn = static_cast<QmlPropertyNode*>(node);
out() << "<div class=\"qmlproto\">";
out() << "<table class=\"qmlname\">";
out() << "<div class=\"table\"><table class=\"qmlname\">";
out() << "<tr valign=\"top\" class=\"odd\" id=\"" << nodeRef << "\">";
out() << "<td class=\"tblQmlPropNode\"><p>";
out() << "<a name=\"" + refForNode(qpn) + "\"></a>";
@ -4103,43 +4122,43 @@ void HtmlGenerator::generateDetailedQmlMember(Node *node,
out() << "<span class=\"qmldefault\">default</span>";
generateQmlItem(qpn, relative, marker, false);
out() << "</p></td></tr>";
out() << "</table>";
out() << "</table></div>";
out() << "</div>";
}
else if (node->type() == Node::QmlSignal) {
const FunctionNode* qsn = static_cast<const FunctionNode*>(node);
out() << "<div class=\"qmlproto\">";
out() << "<table class=\"qmlname\">";
out() << "<div class=\"table\"><table class=\"qmlname\">";
out() << "<tr valign=\"top\" class=\"odd\" id=\"" << nodeRef << "\">";
out() << "<td class=\"tblQmlFuncNode\"><p>";
out() << "<a name=\"" + refForNode(qsn) + "\"></a>";
generateSynopsis(qsn,relative,marker,CodeMarker::Detailed,false);
out() << "</p></td></tr>";
out() << "</table>";
out() << "</table></div>";
out() << "</div>";
}
else if (node->type() == Node::QmlSignalHandler) {
const FunctionNode* qshn = static_cast<const FunctionNode*>(node);
out() << "<div class=\"qmlproto\">";
out() << "<table class=\"qmlname\">";
out() << "<div class=\"table\"><table class=\"qmlname\">";
out() << "<tr valign=\"top\" class=\"odd\" id=\"" << nodeRef << "\">";
out() << "<td class=\"tblQmlFuncNode\"><p>";
out() << "<a name=\"" + refForNode(qshn) + "\"></a>";
generateSynopsis(qshn,relative,marker,CodeMarker::Detailed,false);
out() << "</p></td></tr>";
out() << "</table>";
out() << "</table></div>";
out() << "</div>";
}
else if (node->type() == Node::QmlMethod) {
const FunctionNode* qmn = static_cast<const FunctionNode*>(node);
out() << "<div class=\"qmlproto\">";
out() << "<table class=\"qmlname\">";
out() << "<div class=\"table\"><table class=\"qmlname\">";
out() << "<tr valign=\"top\" class=\"odd\" id=\"" << nodeRef << "\">";
out() << "<td class=\"tblQmlFuncNode\"><p>";
out() << "<a name=\"" + refForNode(qmn) + "\"></a>";
generateSynopsis(qmn,relative,marker,CodeMarker::Detailed,false);
out() << "</p></td></tr>";
out() << "</table>";
out() << "</table></div>";
out() << "</div>";
}
out() << "<div class=\"qmldoc\">";

View File

@ -144,6 +144,7 @@ private:
void generateTableOfContents(const Node *node,
CodeMarker *marker,
QList<Section>* sections = 0);
void generateSidebar();
QString generateListOfAllMemberFile(const InnerNode *inner,
CodeMarker *marker);
QString generateAllQmlMembersFile(QmlClassNode* qml_cn, CodeMarker* marker);
@ -238,6 +239,7 @@ private:
QString endHeader;
QString postHeader;
QString postPostHeader;
QString prologue;
QString footer;
QString address;
bool pleaseGenerateMacRef;
@ -272,6 +274,7 @@ public:
#define HTMLGENERATOR_GENERATEMACREFS "generatemacrefs" // ### document me
#define HTMLGENERATOR_POSTHEADER "postheader"
#define HTMLGENERATOR_POSTPOSTHEADER "postpostheader"
#define HTMLGENERATOR_PROLOGUE "prologue"
#define HTMLGENERATOR_NONAVIGATIONBAR "nonavigationbar"
#define HTMLGENERATOR_NOSUBDIRS "nosubdirs"
#define HTMLGENERATOR_TOCDEPTH "tocdepth"