From 8687e163757df00c1e64c15ad63680ed5c2f6937 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Wed, 13 Oct 2021 20:17:09 +0200 Subject: qdoc: Add styling for \note, \important and \warning And add Atom types for Warning instead of simply hard-coding a bold warning note. Fix a compiler warning for tst_generatedoutput in passing. Pick-to: 6.2 5.15 Fixes: QTBUG-97448 Change-Id: I1fe691ffaadc549b17c8628817fe761d3be0fad7 Reviewed-by: Paul Wicking --- src/qdoc/atom.cpp | 2 ++ src/qdoc/atom.h | 2 ++ src/qdoc/docbookgenerator.cpp | 10 ++++++--- src/qdoc/docparser.cpp | 6 +----- src/qdoc/htmlgenerator.cpp | 25 +++++++++++----------- src/qdoc/webxmlgenerator.cpp | 13 +++++++---- .../qdoctests-qdocfileoutput-exhaustive.xml | 4 +++- .../nestedmacro/testcpp-module.html | 2 ++ .../expected_output/noautolist/testcpp-module.html | 2 ++ .../qdoctests-qdocfileoutput-exhaustive.html | 11 ++++++++-- .../expected_output/testcpp-module.html | 2 ++ .../qdoc/generatedoutput/tst_generatedoutput.cpp | 4 ++-- 12 files changed, 54 insertions(+), 29 deletions(-) diff --git a/src/qdoc/atom.cpp b/src/qdoc/atom.cpp index 2844e8b33..eafaac764 100644 --- a/src/qdoc/atom.cpp +++ b/src/qdoc/atom.cpp @@ -233,6 +233,8 @@ static const struct { "TableOfContents", Atom::TableOfContents }, { "Target", Atom::Target }, { "UnhandledFormat", Atom::UnhandledFormat }, + { "WarningLeft", Atom::WarningLeft }, + { "WarningRight", Atom::WarningRight }, { "UnknownCommand", Atom::UnknownCommand }, { nullptr, 0 } }; diff --git a/src/qdoc/atom.h b/src/qdoc/atom.h index 77a058a70..544e8369b 100644 --- a/src/qdoc/atom.h +++ b/src/qdoc/atom.h @@ -128,6 +128,8 @@ public: TableOfContents, Target, UnhandledFormat, + WarningLeft, + WarningRight, UnknownCommand, Last = UnknownCommand }; diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp index d4ee9374f..2318cb963 100644 --- a/src/qdoc/docbookgenerator.cpp +++ b/src/qdoc/docbookgenerator.cpp @@ -494,14 +494,18 @@ qsizetype DocBookGenerator::generateAtom(const Atom *atom, const Node *relative) case Atom::ImageText: break; case Atom::ImportantLeft: - case Atom::NoteLeft: { - QString tag = atom->type() == Atom::ImportantLeft ? "important" : "note"; - m_writer->writeStartElement(dbNamespace, tag); + case Atom::NoteLeft: + case Atom::WarningLeft: { + QString admonType = atom->typeString().toLower(); + // Remove 'Left' to get the admonition type + admonType.chop(4); + m_writer->writeStartElement(dbNamespace, admonType); newLine(); m_writer->writeStartElement(dbNamespace, "para"); } break; case Atom::ImportantRight: case Atom::NoteRight: + case Atom::WarningRight: m_writer->writeEndElement(); // para newLine(); m_writer->writeEndElement(); // note/important diff --git a/src/qdoc/docparser.cpp b/src/qdoc/docparser.cpp index 814c5fee6..1294f5d7a 100644 --- a/src/qdoc/docparser.cpp +++ b/src/qdoc/docparser.cpp @@ -1078,11 +1078,7 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate, break; case CMD_WARNING: leavePara(); - enterPara(); - append(Atom::FormattingLeft, ATOM_FORMATTING_BOLD); - append(Atom::String, "Warning:"); - append(Atom::FormattingRight, ATOM_FORMATTING_BOLD); - append(Atom::String, " "); + enterPara(Atom::WarningLeft, Atom::WarningRight); break; case CMD_OVERLOAD: m_private->m_metacommandsUsed.insert(cmdStr); diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp index ba273c490..ccde100f8 100644 --- a/src/qdoc/htmlgenerator.cpp +++ b/src/qdoc/htmlgenerator.cpp @@ -644,23 +644,24 @@ qsizetype HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, Co } break; case Atom::ImageText: break; + // Admonitions case Atom::ImportantLeft: - out() << "

"; - out() << formattingLeftMap()[ATOM_FORMATTING_BOLD]; - out() << "Important: "; - out() << formattingRightMap()[ATOM_FORMATTING_BOLD]; - break; - case Atom::ImportantRight: - out() << "

"; - break; case Atom::NoteLeft: - out() << "

"; + case Atom::WarningLeft: { + QString admonType = atom->typeString(); + // Remove 'Left' from atom type to get the admonition type + admonType.chop(4); + out() << "

\n" + << "

"; out() << formattingLeftMap()[ATOM_FORMATTING_BOLD]; - out() << "Note: "; + out() << admonType << ": "; out() << formattingRightMap()[ATOM_FORMATTING_BOLD]; - break; + } break; + case Atom::ImportantRight: case Atom::NoteRight: - out() << "

\n"; + case Atom::WarningRight: + out() << "

\n" + << "
\n"; break; case Atom::LegaleseLeft: out() << "
"; diff --git a/src/qdoc/webxmlgenerator.cpp b/src/qdoc/webxmlgenerator.cpp index 29a74754a..2f8f772b5 100644 --- a/src/qdoc/webxmlgenerator.cpp +++ b/src/qdoc/webxmlgenerator.cpp @@ -532,10 +532,6 @@ const Atom *WebXMLGenerator::addAtomElements(QXmlStreamWriter &writer, const Ato writer.writeCharacters(" "); break; - case Atom::ImportantRight: - writer.writeEndElement(); // para - break; - case Atom::LegaleseLeft: writer.writeStartElement("legalese"); break; @@ -612,7 +608,10 @@ const Atom *WebXMLGenerator::addAtomElements(QXmlStreamWriter &writer, const Ato writer.writeCharacters(" "); break; + // End admonition elements + case Atom::ImportantRight: case Atom::NoteRight: + case Atom::WarningRight: writer.writeEndElement(); // para break; @@ -737,6 +736,12 @@ const Atom *WebXMLGenerator::addAtomElements(QXmlStreamWriter &writer, const Ato writer.writeEndElement(); break; + case Atom::WarningLeft: + writer.writeStartElement("para"); + writer.writeTextElement("bold", "Warning:"); + writer.writeCharacters(" "); + break; + case Atom::UnhandledFormat: case Atom::UnknownCommand: writer.writeCharacters(atom->typeString()); diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml index af2fdd955..7d9ed16f0 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput-exhaustive.xml @@ -57,7 +57,9 @@ The code above doesn't compile -Warning: The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode + +The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode + diff --git a/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html b/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html index f3de1542a..4bc14d345 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/nestedmacro/testcpp-module.html @@ -33,7 +33,9 @@

Detailed Description

+

Note: This is just a test.

+

This module was introduced in version 5.15.

diff --git a/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html b/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html index fd5beda6d..6db15ca22 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/noautolist/testcpp-module.html @@ -21,8 +21,10 @@

Detailed Description

+

Note: This is just a test.

+
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html index 508c12398..cbf7d6894 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput-exhaustive.html @@ -42,13 +42,20 @@ Table item in a table row Another item in a different row
-

Important: This is really important.

For example, if you have code like

+
+

Important: This is really important.

+
+

For example, if you have code like

This is old code.

you can rewrite it as

This is new and shiny!
+

Note: The code above doesn't compile

+
-

Warning: The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode

+
+

Warning: The following commands have yet to be tested: footnote link sincelist header index topicref // or just don’t care, remove it image inlineimage printline printto printuntil // what’s the difference between printto and printuntil??? quotefile quotefromfile quotefunction skipline skipto skipuntil span snippet codeline overload sub sup tableofcontents tt uicontrol endmapref endomit underline unicode

+
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html b/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html index 117f34d72..04bd8e487 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/testcpp-module.html @@ -33,8 +33,10 @@

Detailed Description

+

Note: This is just a test.

+
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp index 7473546b9..ccb131222 100644 --- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp +++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp @@ -105,8 +105,8 @@ void tst_generatedOutput::initTestCase() // Resolve the path to the file containing extra parameters m_extraParams = QFileInfo(QTest::currentAppName()).dir().filePath("qdocincludepaths.inc"); if (!QFileInfo::exists(m_extraParams)) { - const QString warningMessage = "Cannot locate " + m_extraParams; - qWarning(qPrintable(warningMessage)); + qWarning().nospace() << QStringLiteral("Cannot locate") + << qUtf8Printable(m_extraParams); m_extraParams.clear(); } else { m_extraParams.insert(0, '@'); -- cgit v1.2.3