From 6d968dd75567fe281d4a303ae7e882db0bb45ab2 Mon Sep 17 00:00:00 2001 From: Friedemann Kleint Date: Fri, 18 Jun 2021 14:04:33 +0200 Subject: shiboken6/Doc generator: Dedent documentation code snippets Split out helpers for fixing code snippets from class CodeSnipAbstract (which is necessary since the QtXmlToSphinx test is compiled from single source files) and use them. Fixes a number of sphinx warnings about "Unexpected indentation" in data visualization examples. Change-Id: I109f5f6a8158689f5c966630f1b29d797b48607d Reviewed-by: Cristian Maureira-Fredes (cherry picked from commit 772f117d30c567c397944d62c9084360bb071d83) Reviewed-by: Christian Tismer --- sources/shiboken6/ApiExtractor/CMakeLists.txt | 1 + sources/shiboken6/ApiExtractor/codesniphelpers.cpp | 102 +++++++++++++++++++++ sources/shiboken6/ApiExtractor/codesniphelpers.h | 42 +++++++++ sources/shiboken6/ApiExtractor/modifications.cpp | 69 -------------- sources/shiboken6/ApiExtractor/modifications.h | 6 +- .../shiboken6/generator/qtdoc/qtxmltosphinx.cpp | 5 +- .../tests/qtxmltosphinxtest/CMakeLists.txt | 1 + 7 files changed, 151 insertions(+), 75 deletions(-) create mode 100644 sources/shiboken6/ApiExtractor/codesniphelpers.cpp create mode 100644 sources/shiboken6/ApiExtractor/codesniphelpers.h diff --git a/sources/shiboken6/ApiExtractor/CMakeLists.txt b/sources/shiboken6/ApiExtractor/CMakeLists.txt index 48bc3abbc..db624d253 100644 --- a/sources/shiboken6/ApiExtractor/CMakeLists.txt +++ b/sources/shiboken6/ApiExtractor/CMakeLists.txt @@ -15,6 +15,7 @@ abstractmetafield.cpp abstractmetafunction.cpp abstractmetatype.cpp abstractmetalang.cpp +codesniphelpers.cpp documentation.cpp enclosingclassmixin.cpp fileout.cpp diff --git a/sources/shiboken6/ApiExtractor/codesniphelpers.cpp b/sources/shiboken6/ApiExtractor/codesniphelpers.cpp new file mode 100644 index 000000000..f9bae0a65 --- /dev/null +++ b/sources/shiboken6/ApiExtractor/codesniphelpers.cpp @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qt for Python. +** +** $QT_BEGIN_LICENSE:GPL-EXCEPT$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3 as published by the Free Software +** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "codesniphelpers.h" + +#include + +#include + +static inline int firstNonBlank(QStringView s) +{ + const auto it = std::find_if(s.cbegin(), s.cend(), + [] (QChar c) { return !c.isSpace(); }); + return int(it - s.cbegin()); +} + +static inline bool isEmpty(QStringView s) +{ + return s.isEmpty() + || std::all_of(s.cbegin(), s.cend(), + [] (QChar c) { return c.isSpace(); }); +} + +QString CodeSnipHelpers::dedent(const QString &code) +{ + if (code.isEmpty()) + return code; + // Right trim if indent=0, or trim if single line + if (!code.at(0).isSpace() || !code.contains(QLatin1Char('\n'))) + return code.trimmed(); + const auto lines = QStringView{code}.split(QLatin1Char('\n')); + int spacesToRemove = std::numeric_limits::max(); + for (const auto &line : lines) { + if (!isEmpty(line)) { + const int nonSpacePos = firstNonBlank(line); + if (nonSpacePos < spacesToRemove) + spacesToRemove = nonSpacePos; + if (spacesToRemove == 0) + return code; + } + } + QString result; + for (const auto &line : lines) { + if (!isEmpty(line) && spacesToRemove < line.size()) + result += line.mid(spacesToRemove).toString(); + result += QLatin1Char('\n'); + } + return result; +} + +QString CodeSnipHelpers::fixSpaces(QString code) +{ + code.remove(QLatin1Char('\r')); + // Check for XML \nbla... + if (code.startsWith(QLatin1String("\n "))) + code.remove(0, 1); + while (!code.isEmpty() && code.back().isSpace()) + code.chop(1); + code = dedent(code); + if (!code.isEmpty() && !code.endsWith(QLatin1Char('\n'))) + code.append(QLatin1Char('\n')); + return code; +} + +// Prepend a line to the code, observing indentation +void CodeSnipHelpers::prependCode(QString *code, QString firstLine) +{ + while (!code->isEmpty() && code->front() == QLatin1Char('\n')) + code->remove(0, 1); + if (!code->isEmpty() && code->front().isSpace()) { + const int indent = firstNonBlank(*code); + firstLine.prepend(QString(indent, QLatin1Char(' '))); + } + if (!firstLine.endsWith(QLatin1Char('\n'))) + firstLine += QLatin1Char('\n'); + code->prepend(firstLine); +} diff --git a/sources/shiboken6/ApiExtractor/codesniphelpers.h b/sources/shiboken6/ApiExtractor/codesniphelpers.h new file mode 100644 index 000000000..d7da05ea0 --- /dev/null +++ b/sources/shiboken6/ApiExtractor/codesniphelpers.h @@ -0,0 +1,42 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qt for Python. +** +** $QT_BEGIN_LICENSE:GPL-EXCEPT$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3 as published by the Free Software +** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef CODESNIPHELPERS_H +#define CODESNIPHELPERS_H + +#include + +class CodeSnipHelpers +{ +public: + static QString fixSpaces(QString code); + static QString dedent(const QString &code); + static void prependCode(QString *code, QString firstLine); +}; + +#endif // CODESNIPHELPERS_H diff --git a/sources/shiboken6/ApiExtractor/modifications.cpp b/sources/shiboken6/ApiExtractor/modifications.cpp index 645934e3b..1b97eefde 100644 --- a/sources/shiboken6/ApiExtractor/modifications.cpp +++ b/sources/shiboken6/ApiExtractor/modifications.cpp @@ -83,75 +83,6 @@ void CodeSnipAbstract::addCode(const QString &code) codeList.append(CodeSnipFragment(fixSpaces(code))); } -static inline int firstNonBlank(QStringView s) -{ - const auto it = std::find_if(s.cbegin(), s.cend(), - [] (QChar c) { return !c.isSpace(); }); - return int(it - s.cbegin()); -} - -static inline bool isEmpty(QStringView s) -{ - return s.isEmpty() - || std::all_of(s.cbegin(), s.cend(), - [] (QChar c) { return c.isSpace(); }); -} - -QString CodeSnipAbstract::dedent(const QString &code) -{ - if (code.isEmpty()) - return code; - // Right trim if indent=0, or trim if single line - if (!code.at(0).isSpace() || !code.contains(QLatin1Char('\n'))) - return code.trimmed(); - const auto lines = QStringView{code}.split(QLatin1Char('\n')); - int spacesToRemove = std::numeric_limits::max(); - for (const auto &line : lines) { - if (!isEmpty(line)) { - const int nonSpacePos = firstNonBlank(line); - if (nonSpacePos < spacesToRemove) - spacesToRemove = nonSpacePos; - if (spacesToRemove == 0) - return code; - } - } - QString result; - for (const auto &line : lines) { - if (!isEmpty(line) && spacesToRemove < line.size()) - result += line.mid(spacesToRemove).toString(); - result += QLatin1Char('\n'); - } - return result; -} - -QString CodeSnipAbstract::fixSpaces(QString code) -{ - code.remove(QLatin1Char('\r')); - // Check for XML \nbla... - if (code.startsWith(QLatin1String("\n "))) - code.remove(0, 1); - while (!code.isEmpty() && code.back().isSpace()) - code.chop(1); - code = dedent(code); - if (!code.isEmpty() && !code.endsWith(QLatin1Char('\n'))) - code.append(QLatin1Char('\n')); - return code; -} - -// Prepend a line to the code, observing indentation -void CodeSnipAbstract::prependCode(QString *code, QString firstLine) -{ - while (!code->isEmpty() && code->front() == QLatin1Char('\n')) - code->remove(0, 1); - if (!code->isEmpty() && code->front().isSpace()) { - const int indent = firstNonBlank(*code); - firstLine.prepend(QString(indent, QLatin1Char(' '))); - } - if (!firstLine.endsWith(QLatin1Char('\n'))) - firstLine += QLatin1Char('\n'); - code->prepend(firstLine); -} - QRegularExpression CodeSnipAbstract::placeHolderRegex(int index) { return QRegularExpression(QLatin1Char('%') + QString::number(index) + QStringLiteral("\\b")); diff --git a/sources/shiboken6/ApiExtractor/modifications.h b/sources/shiboken6/ApiExtractor/modifications.h index 09527d4ad..c79184cbe 100644 --- a/sources/shiboken6/ApiExtractor/modifications.h +++ b/sources/shiboken6/ApiExtractor/modifications.h @@ -31,6 +31,7 @@ #include "typesystem_enums.h" #include "typesystem_typedefs.h" +#include "codesniphelpers.h" #include "parser/typeinfo.h" #include @@ -120,7 +121,7 @@ private: TemplateInstance *m_instance = nullptr; }; -class CodeSnipAbstract +class CodeSnipAbstract : public CodeSnipHelpers { public: QString code() const; @@ -135,9 +136,6 @@ public: QList codeList; - static QString fixSpaces(QString code); - static QString dedent(const QString &code); - static void prependCode(QString *code, QString firstLine); static QRegularExpression placeHolderRegex(int index); }; diff --git a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp index 52d8f4614..693904b09 100644 --- a/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp +++ b/sources/shiboken6/generator/qtdoc/qtxmltosphinx.cpp @@ -28,6 +28,7 @@ #include "qtxmltosphinx.h" #include "qtxmltosphinxinterface.h" +#include #include "rstformat.h" #include @@ -520,7 +521,7 @@ QString QtXmlToSphinx::readFromLocation(const QString &location, const QString & if (identifier.isEmpty()) { while (!inputFile.atEnd()) code += QString::fromUtf8(inputFile.readLine()); - return code; + return CodeSnipHelpers::fixSpaces(code); } const QRegularExpression searchString(QLatin1String("//!\\s*\\[") @@ -550,7 +551,7 @@ QString QtXmlToSphinx::readFromLocation(const QString &location, const QString & return QString(); // null } - return code; + return CodeSnipHelpers::fixSpaces(code); } void QtXmlToSphinx::handleHeadingTag(QXmlStreamReader& reader) diff --git a/sources/shiboken6/tests/qtxmltosphinxtest/CMakeLists.txt b/sources/shiboken6/tests/qtxmltosphinxtest/CMakeLists.txt index 3c1df916e..940a171b5 100644 --- a/sources/shiboken6/tests/qtxmltosphinxtest/CMakeLists.txt +++ b/sources/shiboken6/tests/qtxmltosphinxtest/CMakeLists.txt @@ -12,6 +12,7 @@ set(api_extractor_src_dir ${CMAKE_CURRENT_SOURCE_DIR}/../../ApiExtractor) set(qtxmltosphinxtest_SRC ${generator_src_dir}/qtdoc/qtxmltosphinx.cpp + ${api_extractor_src_dir}/codesniphelpers.cpp ${api_extractor_src_dir}/textstream.cpp qtxmltosphinxtest.cpp qtxmltosphinxtest.h) -- cgit v1.2.3