From 1ad78f5f29ef00abae4f718265fa4bc0c35b60f9 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Tue, 21 Oct 2014 10:22:45 +0200 Subject: 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 tags with 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
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 --- src/tools/qdoc/cppcodemarker.cpp | 12 ++--- src/tools/qdoc/htmlgenerator.cpp | 109 +++++++++++++++++++++++---------------- src/tools/qdoc/htmlgenerator.h | 3 ++ 3 files changed, 73 insertions(+), 51 deletions(-) (limited to 'src/tools') diff --git a/src/tools/qdoc/cppcodemarker.cpp b/src/tools/qdoc/cppcodemarker.cpp index 48218da513..92b6ccca6a 100644 --- a/src/tools/qdoc/cppcodemarker.cpp +++ b/src/tools/qdoc/cppcodemarker.cpp @@ -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()) + "::​"); 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: @@ -283,13 +283,13 @@ QString CppCodeMarker::markedUpSynopsis(const Node *node, if (style == Summary) { if (node->status() == Node::Preliminary) { - extra += " (preliminary)"; + extra += "(preliminary) "; } else if (node->status() == Node::Deprecated) { - extra += " (deprecated)"; + extra += "(deprecated) "; } else if (node->status() == Node::Obsolete) { - extra += " (obsolete)"; + extra += "(obsolete) "; } } @@ -297,7 +297,7 @@ QString CppCodeMarker::markedUpSynopsis(const Node *node, extra.prepend("<@extra>"); extra.append(""); } - return synopsis + extra; + return extra + synopsis; } /*! diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp index 5b8ccd9902..bd8d45ab53 100644 --- a/src/tools/qdoc/htmlgenerator.cpp +++ b/src/tools/qdoc/htmlgenerator.cpp @@ -121,7 +121,7 @@ void HtmlGenerator::initializeGenerator(const Config &config) { ATOM_FORMATTING_PARAMETER, "", "" }, { ATOM_FORMATTING_SUBSCRIPT, "", "" }, { ATOM_FORMATTING_SUPERSCRIPT, "", "" }, - { ATOM_FORMATTING_TELETYPE, "", "" }, + { ATOM_FORMATTING_TELETYPE, "", "" }, // tag is not supported in HTML5 { ATOM_FORMATTING_UICONTROL, "", "" }, { ATOM_FORMATTING_UNDERLINE, "", "" }, { 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() << "
\n"; } else if (atom->string() == ATOM_LIST_VALUE) { - out() << ""; + out() << "
"; 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() << "
" << t << ""; + out() << "
" << t << ""; if (relative->type() == Node::Enum) { out() << ""; @@ -907,7 +911,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark if (itemValue.isEmpty()) out() << '?'; else - out() << "" << protectEnc(itemValue) << ""; + out() << "" << protectEnc(itemValue) << ""; } skipAhead = 1; } @@ -952,7 +956,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark out() << "\n"; } else if (atom->string() == ATOM_LIST_VALUE) { - out() << "
\n"; + out() << "
\n"; } else { out() << "\n"; @@ -1040,7 +1044,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark else if (p2.contains("%")) width = p2; } - out() << "
\n "; @@ -1048,7 +1052,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark } break; case Atom::TableRight: - out() << "
\n"; + out() << "\n"; break; case Atom::TableHeaderLeft: out() << ""; @@ -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("\n"); #endif - out() << "\n"; - out() << QString("\n").arg(naturalLanguage); + out() << "\n"; + out() << QString("\n").arg(naturalLanguage); out() << "\n"; out() << " \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() << "
  • \n" << buildversion << "
    • \n"; + if (!buildversion.isEmpty()) + out() << "
  • " << buildversion << "
    • \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() << "

    " << protectEnc(title) << "

    \n"; if (!subTitle.isEmpty()) { @@ -1993,7 +1998,7 @@ void HtmlGenerator::generateRequisites(InnerNode *inner, CodeMarker *marker) if (!requisites.isEmpty()) { //generate the table - out() << "\n"; + out() << "
    \n"; QStringList::ConstIterator i; for (i = requisiteorder.begin(); i != requisiteorder.constEnd(); ++i) { @@ -2011,7 +2016,7 @@ void HtmlGenerator::generateRequisites(InnerNode *inner, CodeMarker *marker) out() << ""; } } - out() << "
    "; + out() << ""; } } @@ -2112,7 +2117,7 @@ void HtmlGenerator::generateQmlRequisites(QmlClassNode *qcn, CodeMarker *marker) if (!requisites.isEmpty()) { //generate the table - out() << "\n"; + out() << "
    \n"; QStringList::ConstIterator i; for (i = requisiteorder.begin(); i != requisiteorder.constEnd(); ++i) { @@ -2130,7 +2135,7 @@ void HtmlGenerator::generateQmlRequisites(QmlClassNode *qcn, CodeMarker *marker) out() << ""; } } - out() << "
    "; + out() << ""; } } @@ -2176,12 +2181,10 @@ void HtmlGenerator::generateTableOfContents(const Node *node, QList 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() << "
    \n"; out() << "
    \n"; out() << "

    Contents

    \n"; sectionNumber.append("1"); @@ -2287,10 +2291,21 @@ void HtmlGenerator::generateTableOfContents(const Node *node, } out() << "\n"; out() << "
    \n"; + out() << "
    "; + out() << "
    \n"; inContents_ = false; inLink_ = false; } +/*! + Outputs a placeholder div where the style can add customized sidebar content. + */ +void HtmlGenerator::generateSidebar() { + out() << "
    "; + out() << "
    "; + out() << "
    \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() << "

    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() << "

    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() << "

    The following members of QML type " @@ -2615,7 +2634,7 @@ void HtmlGenerator::generateAnnotatedList(const Node *relative, } if (allInternal) return; - out() << "\n"; + out() << "
    \n"; int row = 0; NodeList nodes = nm.values(); foreach (const Node* node, nodes) { @@ -2651,7 +2670,7 @@ void HtmlGenerator::generateAnnotatedList(const Node *relative, } out() << "\n"; } - out() << "
    \n"; + out() << "\n"; } /*! @@ -2902,8 +2921,8 @@ void HtmlGenerator::generateQmlItem(const Node *node, if (summary) marked.replace("@name>", "b>"); - marked.replace("<@extra>", ""); - marked.replace("", ""); + marked.replace("<@extra>", ""); + marked.replace("", ""); if (summary) { marked.remove("<@type>"); @@ -3027,11 +3046,11 @@ void HtmlGenerator::generateSection(const NodeList& nl, alignNames = false; } if (alignNames) { - out() << "\n"; + out() << "
    \n"; } else { if (twoColumn) - out() << "
    \n" + out() << "
    \n" << "
    "; out() << "
      \n"; } @@ -3062,11 +3081,11 @@ void HtmlGenerator::generateSection(const NodeList& nl, ++m; } if (alignNames) - out() << "
    \n"; + out() << "\n"; else { out() << "\n"; if (twoColumn) - out() << "\n\n"; + out() << "\n\n"; } } } @@ -3088,11 +3107,11 @@ void HtmlGenerator::generateSectionList(const Section& section, alignNames = false; } if (alignNames) { - out() << "\n"; + out() << "
    \n"; } else { if (twoColumn) - out() << "
    \n" + out() << "
    \n" << "
    "; out() << "
      \n"; } @@ -3128,11 +3147,11 @@ void HtmlGenerator::generateSectionList(const Section& section, ++m; } if (alignNames) - out() << "
    \n"; + out() << "\n"; else { out() << "\n"; if (twoColumn) - out() << "\n\n"; + out() << "\n\n"; } } @@ -3196,8 +3215,8 @@ void HtmlGenerator::generateSynopsis(const Node *node, extraRegExp.setMinimal(true); marked.remove(extraRegExp); } else { - marked.replace("<@extra>", ""); - marked.replace("", ""); + marked.replace("<@extra>", ""); + marked.replace("", ""); } if (style != CodeMarker::Detailed) { @@ -4058,7 +4077,7 @@ void HtmlGenerator::generateDetailedQmlMember(Node *node, const QmlPropertyGroupNode* qpgn = static_cast(node); NodeList::ConstIterator p = qpgn->childNodes().constBegin(); out() << "

    "; - out() << ""; + out() << "
    "; QString heading = qpgn->name() + " group"; out() << ""; @@ -4083,13 +4102,13 @@ void HtmlGenerator::generateDetailedQmlMember(Node *node, } ++p; } - out() << "
    "; + out() << "
    "; out() << ""; } else if (node->type() == Node::QmlProperty) { qpn = static_cast(node); out() << "
    "; - out() << ""; + out() << "
    "; out() << ""; out() << ""; - out() << "

    "; out() << ""; @@ -4103,43 +4122,43 @@ void HtmlGenerator::generateDetailedQmlMember(Node *node, out() << "default"; generateQmlItem(qpn, relative, marker, false); out() << "

    "; + out() << "
    "; out() << ""; } else if (node->type() == Node::QmlSignal) { const FunctionNode* qsn = static_cast(node); out() << "
    "; - out() << ""; + out() << "
    "; out() << ""; out() << ""; - out() << "

    "; out() << ""; generateSynopsis(qsn,relative,marker,CodeMarker::Detailed,false); out() << "

    "; + out() << "
    "; out() << ""; } else if (node->type() == Node::QmlSignalHandler) { const FunctionNode* qshn = static_cast(node); out() << "
    "; - out() << ""; + out() << "
    "; out() << ""; out() << ""; - out() << "

    "; out() << ""; generateSynopsis(qshn,relative,marker,CodeMarker::Detailed,false); out() << "

    "; + out() << "
    "; out() << ""; } else if (node->type() == Node::QmlMethod) { const FunctionNode* qmn = static_cast(node); out() << "
    "; - out() << ""; + out() << "
    "; out() << ""; out() << ""; - out() << "

    "; out() << ""; generateSynopsis(qmn,relative,marker,CodeMarker::Detailed,false); out() << "

    "; + out() << "
    "; out() << ""; } out() << "
    "; diff --git a/src/tools/qdoc/htmlgenerator.h b/src/tools/qdoc/htmlgenerator.h index 616a989361..40360da02e 100644 --- a/src/tools/qdoc/htmlgenerator.h +++ b/src/tools/qdoc/htmlgenerator.h @@ -144,6 +144,7 @@ private: void generateTableOfContents(const Node *node, CodeMarker *marker, QList
    * 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" -- cgit v1.2.3