diff options
author | Jaishree Vyas <Jaishree.Vyas@qt.io> | 2023-03-01 11:59:11 +0100 |
---|---|---|
committer | Jaishree Vyas <Jaishree.Vyas@qt.io> | 2023-04-19 11:45:58 +0200 |
commit | b968ed6bc09d363f96ab6761f88fde790f7f09b1 (patch) | |
tree | 53bbaa68eaa921c4f2936f0e6fb1d70548c27438 | |
parent | 263741618ba33be5cb69d3e63c1eafb566a77449 (diff) | |
download | qttools-b968ed6bc09d363f96ab6761f88fde790f7f09b1.tar.gz |
qdoc: Add \details command
The command \details generates a collapsible <details>
element with a <summary> to control the hidden/visible
state.
The idea behind this is to provide more information with
less text on our main pages.
For output formats other than HTML, the details are
rendered as a normal paragraph and the summary string
is ignored.
Pick-to: 6.5
Change-Id: Id5daddd4854f22b9ceaa9a55b98af94a1ba06039
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
11 files changed, 98 insertions, 1 deletions
diff --git a/src/qdoc/qdoc/atom.cpp b/src/qdoc/qdoc/atom.cpp index 6b895769f..080a8fddd 100644 --- a/src/qdoc/qdoc/atom.cpp +++ b/src/qdoc/qdoc/atom.cpp @@ -50,6 +50,8 @@ QT_BEGIN_NAMESPACE \value CodeBad \value CodeQuoteArgument \value CodeQuoteCommand + \value DetailsLeft + \value DetailsRight \value DivLeft \value DivRight \value ExampleFileLink @@ -130,6 +132,8 @@ static const struct { "CodeBad", Atom::CodeBad }, { "CodeQuoteArgument", Atom::CodeQuoteArgument }, { "CodeQuoteCommand", Atom::CodeQuoteCommand }, + { "DetailsLeft", Atom::DetailsLeft }, + { "DetailsRight", Atom::DetailsRight }, { "DivLeft", Atom::DivLeft }, { "DivRight", Atom::DivRight }, { "ExampleFileLink", Atom::ExampleFileLink }, diff --git a/src/qdoc/qdoc/atom.h b/src/qdoc/qdoc/atom.h index ba453254b..3e642a6dd 100644 --- a/src/qdoc/qdoc/atom.h +++ b/src/qdoc/qdoc/atom.h @@ -31,6 +31,8 @@ public: CodeBad, CodeQuoteArgument, CodeQuoteCommand, + DetailsLeft, + DetailsRight, DivLeft, DivRight, ExampleFileLink, diff --git a/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc index 04d9f7cc3..714db3664 100644 --- a/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -173,6 +173,46 @@ See also \l {tt-command} {\\tt} and \l {code-command} {\\code}. + \target details-command + \section1 \\details + + The \\details and \\enddetails commands generates a collapsible <details> + element with a <summary> to control the hidden/visible state. + + When generating HTML output, use the \\details and \\enddetails commands to + generate a collapsible \c{<details>} HTML element. The command takes an + optional summary string enclosed in curly braces. This optional argument + specifies a visible heading for the details. + + For example, with the following input: + \badcode * + /\1! + \details {QDoc details} + \note You're looking at detailed information. + \enddetails + \1/ + \endcode + + If QDoc is generating HTML, it will translate these commands to: + + \badcode + <summary>QDoc details</summary><div class="admonition note"><p><b>Note: </b>You're looking at detailed information.</p></div> + \endcode + + QDoc renders this as: + + \raw HTML + <details> + <summary>QDoc details</summary> + <div class="admonition note"> + <p><b>Note: </b>You're looking at detailed information.</p> + </div> + </details> + \endraw + + For any other output format, QDoc generates the contents as a normal paragraph, + ignoring the summary string. + \target div-command \section1 \\div diff --git a/src/qdoc/qdoc/docbookgenerator.cpp b/src/qdoc/qdoc/docbookgenerator.cpp index b849e5453..cc75cac07 100644 --- a/src/qdoc/qdoc/docbookgenerator.cpp +++ b/src/qdoc/qdoc/docbookgenerator.cpp @@ -341,6 +341,9 @@ qsizetype DocBookGenerator::generateAtom(const Atom *atom, const Node *relative) m_writer->writeEndElement(); // programlisting newLine(); break; + case Atom::DetailsLeft: + case Atom::DetailsRight: + break; case Atom::DivLeft: case Atom::DivRight: break; diff --git a/src/qdoc/qdoc/docparser.cpp b/src/qdoc/qdoc/docparser.cpp index c638cde4e..6702d8ed2 100644 --- a/src/qdoc/qdoc/docparser.cpp +++ b/src/qdoc/qdoc/docparser.cpp @@ -36,11 +36,13 @@ enum { CMD_CAPTION, CMD_CODE, CMD_CODELINE, + CMD_DETAILS, CMD_DIV, CMD_DOTS, CMD_E, CMD_ELSE, CMD_ENDCODE, + CMD_ENDDETAILS, CMD_ENDDIV, CMD_ENDFOOTNOTE, CMD_ENDIF, @@ -136,11 +138,13 @@ static struct { "caption", CMD_CAPTION }, { "code", CMD_CODE }, { "codeline", CMD_CODELINE }, + { "details", CMD_DETAILS }, { "div", CMD_DIV }, { "dots", CMD_DOTS }, { "e", CMD_E }, { "else", CMD_ELSE }, { "endcode", CMD_ENDCODE }, + { "enddetails", CMD_ENDDETAILS }, { "enddiv", CMD_ENDDIV }, { "endfootnote", CMD_ENDFOOTNOTE }, { "endif", CMD_ENDIF }, @@ -382,6 +386,16 @@ void DocParser::parse(const QString &source, DocPrivate *docPrivate, getCode(CMD_QML, CodeMarker::markerForLanguage(QLatin1String("QML")), getMetaCommandArgument(cmdStr))); break; + case CMD_DETAILS: + leavePara(); + append(Atom::DetailsLeft, getArgument()); + m_openedCommands.push(cmd); + break; + case CMD_ENDDETAILS: + leavePara(); + append(Atom::DetailsRight); + closeCommand(cmd); + break; case CMD_DIV: leavePara(); p1 = getArgument(true); @@ -1749,7 +1763,8 @@ void DocParser::enterPara(Atom::AtomType leftType, Atom::AtomType rightType, con if (m_paragraphState == OutsideParagraph) { if ((m_private->m_text.lastAtom()->type() != Atom::ListItemLeft) - && (m_private->m_text.lastAtom()->type() != Atom::DivLeft)) { + && (m_private->m_text.lastAtom()->type() != Atom::DivLeft) + && (m_private->m_text.lastAtom()->type() != Atom::DetailsLeft)) { leaveValueList(); } @@ -2425,6 +2440,8 @@ int DocParser::endCmdFor(int cmd) return CMD_ENDCODE; case CMD_CODE: return CMD_ENDCODE; + case CMD_DETAILS: + return CMD_ENDDETAILS; case CMD_DIV: return CMD_ENDDIV; case CMD_QML: diff --git a/src/qdoc/qdoc/htmlgenerator.cpp b/src/qdoc/qdoc/htmlgenerator.cpp index 74ce2be7e..304989f9c 100644 --- a/src/qdoc/qdoc/htmlgenerator.cpp +++ b/src/qdoc/qdoc/htmlgenerator.cpp @@ -370,6 +370,16 @@ qsizetype HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, Co m_codePrefix, m_codeSuffix) << "</pre>\n"; break; + case Atom::DetailsLeft: + out() << "<details>\n"; + if (!atom->string().isEmpty()) + out() << "<summary>" << protectEnc(atom->string()) << "</summary>\n"; + else + out() << "<summary>...</summary>\n"; + break; + case Atom::DetailsRight: + out() << "</details>\n"; + break; case Atom::DivLeft: out() << "<div"; if (!atom->string().isEmpty()) diff --git a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml index 5f7308779..72905681d 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml +++ b/tests/auto/qdoc/generatedoutput/expected_output/docbook/qdoctests-qdocfileoutput.xml @@ -73,5 +73,8 @@ <db:section xml:id="linking-to-something-in-a-section-title"> <db:title>Linking to <db:link xlink:href="qdoctests-qdocfileoutput.xml#further-information">something</db:link> in a section title</db:title> <db:para>This is allowed but a questionable practice.</db:para> +<db:note> +<db:para>You're looking at detailed information.</db:para> +</db:note> </db:section> </db:article> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml index 3eb5b7703..13b3e5c51 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml +++ b/tests/auto/qdoc/generatedoutput/expected_output/html/qdoctests-qdocfileoutput.webxml @@ -86,6 +86,8 @@ <section id="linking-to-something-in-a-section-title"> <heading level="1">Linking to <link raw="Further information" href="qdoctests-qdocfileoutput.html#further-information" type="page" page="Testing QDoc output from .qdoc files">something</link> in a section title</heading> <para>This is allowed but a questionable practice.</para> + <para> + <bold>Note:</bold> You're looking at detailed information.</para> </section> </description> </page> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html index 61b0e8bc1..74570305c 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/qdoctests-qdocfileoutput.html @@ -55,6 +55,12 @@ <p>This section title is overridden by another target which takes precedence.</p> <h2 id="linking-to-something-in-a-section-title">Linking to <a href="qdoctests-qdocfileoutput.html#further-information" translate="no">something</a> in a section title</h2> <p>This is allowed but a questionable practice.</p> +<details> +<summary>QDoc details</summary> +<div class="admonition note"> +<p><b>Note: </b>You're looking at detailed information.</p> +</div> +</details> </div> <!-- @@@qdoctests-qdocfileoutput.html --> <p class="naviNextPrevious footerNavi"> diff --git a/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html b/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html index f9fa82782..cbb55db2e 100644 --- a/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html +++ b/tests/auto/qdoc/generatedoutput/expected_output/tocbreadcrumbs/qdoctests-qdocfileoutput.html @@ -57,6 +57,12 @@ <p>This section title is overridden by another target which takes precedence.</p> <h2 id="linking-to-something-in-a-section-title">Linking to <a href="qdoctests-qdocfileoutput.html#further-information" translate="no">something</a> in a section title</h2> <p>This is allowed but a questionable practice.</p> +<details> +<summary>QDoc details</summary> +<div class="admonition note"> +<p><b>Note: </b>You're looking at detailed information.</p> +</div> +</details> </div> <!-- @@@qdoctests-qdocfileoutput.html --> <p class="naviNextPrevious footerNavi"> diff --git a/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc b/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc index 53fe34666..3deb39807 100644 --- a/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc +++ b/tests/auto/qdoc/generatedoutput/testdata/outputfromqdocfiles/qdoctests-outputfromqdocfiles.qdoc @@ -55,6 +55,10 @@ \section1 Linking to \l {Further information}{something} in a section title This is allowed but a questionable practice. + + \details {\PROD details} + \note You're looking at detailed information. + \enddetails */ /*! |