From 48351cd99854130b02b6621507cc2e7462d9a47b Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Thu, 21 Apr 2022 17:27:51 +0200 Subject: qdoc: Improve generated navigation bar for C++ and QML types QDoc included only the page(s) provided in navigation.cppclassespage and navigation.qmltypespage in the navigation bar (breadcrumbs) generated for type reference pages. If a type is part of some other (sub-)module, include a link to that module specifically after the generic 'C++ Classes' or 'QML Types' link. In passing, fix an issue where QML type pages lost an entry for *this* page on the navigation bar if the navigation config variable was not set. Fixes: QTBUG-102387 Change-Id: I1316082858455938e4f4e2173f527b87c9a78f08 Reviewed-by: Luca Di Sera (cherry picked from commit 106a6e613cf9b70d55a2d0a14f4612d660ef45be) Reviewed-by: Qt Cherry-pick Bot --- src/qdoc/htmlgenerator.cpp | 72 +++++++++++++--------- .../expected_output/dontdocument/seenclass.html | 1 + .../expected_output/ignoresince/testqdoc-test.html | 1 + .../qml-qdoc-test-abstractparent-members.html | 2 + .../qml-qdoc-test-abstractparent.html | 2 + .../properties/testqdoc-testderived-members.html | 1 + .../properties/testqdoc-testderived.html | 1 + .../generatedoutput/expected_output/qml-int.html | 2 + .../qml-linkmodule-grandchild-members.html | 2 + .../qml-qdoc-test-abstractparent.html | 2 + .../expected_output/qml-qdoc-test-child.html | 2 + .../expected_output/qml-qdoc-test-doctest.html | 2 + .../qml-qdoc-test-type-members.html | 2 + .../qml-qdoc-test-type-obsolete.html | 2 + .../expected_output/qml-qdoc-test-type.html | 2 + .../qml-qdoc-test-yetanotherchild.html | 2 + .../qml-test-nover-typenoversion-members.html | 3 + .../qml-test-nover-typenoversion.html | 3 + .../qml-uicomponents-progressbar.html | 3 + .../expected_output/qml-uicomponents-switch.html | 3 + .../qml-uicomponents-tabwidget.html | 3 + .../qml-qdoc-test-anotherchild-members.html | 2 + .../qmlpropertygroups/qml-qdoc-test-parent.html | 2 + .../expected_output/scopedenum/testqdoc-test.html | 1 + .../expected_output/template/bar.html | 1 + .../expected_output/template/baz.html | 1 + .../expected_output/template/foo.html | 1 + .../template/testqdoc-test-struct.html | 1 + .../expected_output/template/testqdoc-test.html | 1 + .../expected_output/template/testqdoc-vec.html | 1 + .../expected_output/testqdoc-test-members.html | 1 + .../expected_output/testqdoc-test-obsolete.html | 1 + .../expected_output/testqdoc-test.html | 1 + .../testqdoc-testderived-members.html | 1 + .../testqdoc-testderived-obsolete.html | 1 + .../expected_output/testqdoc-testderived.html | 1 + .../testdata/configs/testcpp.qdocconf | 2 + .../testdata/configs/testqml.qdocconf | 2 + .../testdata/indexlinking/linking.qdoc | 1 + 39 files changed, 107 insertions(+), 28 deletions(-) diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp index 386e84e54..28dfe235e 100644 --- a/src/qdoc/htmlgenerator.cpp +++ b/src/qdoc/htmlgenerator.cpp @@ -1540,7 +1540,26 @@ QString HtmlGenerator::fileExtension() const } /*! - Output navigation list in the html file. + Output a navigation bar (breadcrumbs) for the html file. + For API reference pages, items for the navigation bar are (in order): + \table + \header \li Item \li Related configuration variable \li Notes + \row \li home \li navigation.homepage \li e.g. 'Qt 6.2' + \row \li landing \li navigation.landingpage \li Module landing page + \row \li types \li navigation.cppclassespage (C++)\br + navigation.qmltypespage (QML) \li Types only + \row \li module \li n/a (automatic) \li Module page if different + from previous item + \row \li page \li n/a \li Current page title + \endtable + + For other page types (page nodes) the navigation bar is constructed from home + page, landing page, and the chain of Node::navigationParent() items (if one exists). + This chain is constructed from the \\list structure on a page or pages defined in + \c navigation.toctitles configuration variable. + + Finally, if no other navigation data exists for a page but it is a member of a + single group (using \\ingroup), add that group page to the navigation bar. */ void HtmlGenerator::generateNavigationBar(const QString &title, const Node *node, CodeMarker *marker, const QString &buildversion, @@ -1552,39 +1571,41 @@ void HtmlGenerator::generateNavigationBar(const QString &title, const Node *node Text navigationbar; // Set list item types based on the navigation bar type + // TODO: Do we still need table items? Atom::AtomType itemLeft = tableItems ? Atom::TableItemLeft : Atom::ListItemLeft; Atom::AtomType itemRight = tableItems ? Atom::TableItemRight : Atom::ListItemRight; + auto addNavItem = [&](const QString &link, const QString &title) { + navigationbar << Atom(itemLeft) << Atom(Atom::NavLink, link) + << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) + << Atom(Atom::String, title) + << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) << Atom(itemRight); + }; + if (m_hometitle == title) return; if (!m_homepage.isEmpty()) - navigationbar << Atom(itemLeft) << Atom(Atom::NavLink, m_homepage) - << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) - << Atom(Atom::String, m_hometitle) - << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) << Atom(itemRight); + addNavItem(m_homepage, m_hometitle); if (!m_landingpage.isEmpty() && m_landingtitle != title) - navigationbar << Atom(itemLeft) << Atom(Atom::NavLink, m_landingpage) - << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) - << Atom(Atom::String, m_landingtitle) - << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) << Atom(itemRight); + addNavItem(m_landingpage, m_landingtitle); if (node->isClassNode()) { if (!m_cppclassespage.isEmpty() && !m_cppclassestitle.isEmpty()) - navigationbar << Atom(itemLeft) << Atom(Atom::NavLink, m_cppclassespage) - << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) - << Atom(Atom::String, m_cppclassestitle) - << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) << Atom(itemRight); - - if (!node->name().isEmpty()) - navigationbar << Atom(itemLeft) << Atom(Atom::String, node->name()) << Atom(itemRight); + addNavItem(m_cppclassespage, m_cppclassestitle); + if (!node->physicalModuleName().isEmpty()) { + // TODO: Abusing addModule() which is just a wrapper for private method findModule() + auto moduleNode = m_qdb->addModule(node->physicalModuleName()); + if (moduleNode && moduleNode->title() != m_cppclassespage) + addNavItem(moduleNode->name(), moduleNode->name()); + } + navigationbar << Atom(itemLeft) << Atom(Atom::String, node->name()) << Atom(itemRight); } else if (node->isQmlType() || node->isQmlBasicType() || node->isJsType() || node->isJsBasicType()) { if (!m_qmltypespage.isEmpty() && !m_qmltypestitle.isEmpty()) - navigationbar << Atom(itemLeft) << Atom(Atom::NavLink, m_qmltypespage) - << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) - << Atom(Atom::String, m_qmltypestitle) - << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) << Atom(itemRight) - << Atom(itemLeft) << Atom(Atom::String, title) << Atom(itemRight); + addNavItem(m_qmltypespage, m_qmltypestitle); + if (node->logicalModule() && node->logicalModule()->title() != m_qmltypespage) + addNavItem(node->logicalModule()->name(), node->logicalModule()->name()); + navigationbar << Atom(itemLeft) << Atom(Atom::String, node->name()) << Atom(itemRight); } else { if (node->isPageNode()) { auto currentNode = node; @@ -1608,13 +1629,8 @@ void HtmlGenerator::generateNavigationBar(const QString &title, const Node *node } } while (!navNodes.empty()) { - if (navNodes.front()->isPageNode()) { - navigationbar << Atom(itemLeft) << Atom(Atom::NavLink, navNodes.front()->name()) - << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) - << Atom(Atom::String, navNodes.front()->title()) - << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK) - << Atom(itemRight); - } + if (navNodes.front()->isPageNode()) + addNavItem(navNodes.front()->name(), navNodes.front()->title()); navNodes.pop_front(); } } diff --git a/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/seenclass.html b/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/seenclass.html index 0e2ff10b5..c0501ee46 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/seenclass.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/seenclass.html @@ -6,6 +6,7 @@ SeenClass Class | TestCPP +
  • C++ Classes
  • SeenClass