shiboken/qtdocgenerator: Fix inline images

The rst ::image elements do not work inline, they require a line
each.

Work around as recommended by using rst substitution references
instead, using a tag enclosed in '|' and defining it below.

Split out a separate inline image handler and store the references
to be written out later.

Fixes warnings like:
WARNING: image file not readable: PySide2/QtCore/images/cursor-cross.pngAcrosshaircursor,typicallyusedtohelptheuseraccuratelyselectapointonthescreen.

Task-number: PYSIDE-363
Change-Id: I860875957688885ca48038aa3aa96bd9c38da709
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>

2 files changed, 57 insertions, 14 deletions

diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
index e2797997b..7cce97ae1 100644
--- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
+++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp
@@ -204,7 +204,7 @@ QtXmlToSphinx::QtXmlToSphinx(QtDocGenerator* generator, const QString& doc, cons
     m_handlerMap.insert(QLatin1String("argument"), &QtXmlToSphinx::handleArgumentTag);
     m_handlerMap.insert(QLatin1String("teletype"), &QtXmlToSphinx::handleArgumentTag);
     m_handlerMap.insert(QLatin1String("link"), &QtXmlToSphinx::handleLinkTag);
-    m_handlerMap.insert(QLatin1String("inlineimage"), &QtXmlToSphinx::handleImageTag);
+    m_handlerMap.insert(QLatin1String("inlineimage"), &QtXmlToSphinx::handleInlineImageTag);
     m_handlerMap.insert(QLatin1String("image"), &QtXmlToSphinx::handleImageTag);
     m_handlerMap.insert(QLatin1String("list"), &QtXmlToSphinx::handleListTag);
     m_handlerMap.insert(QLatin1String("term"), &QtXmlToSphinx::handleTermTag);
@@ -370,6 +370,16 @@ QString QtXmlToSphinx::transform(const QString& doc)
             m_lastTagName = reader.name().toString();
         }
     }
+
+    if (!m_inlineImages.isEmpty()) {
+        // Write out inline image definitions stored in handleInlineImageTag().
+        m_output << endl;
+        for (const InlineImage &img : qAsConst(m_inlineImages))
+            m_output << ".. |" << img.tag << "| image:: " << img.href << endl;
+        m_output << endl;
+        m_inlineImages.clear();
+    }
+
     m_output.flush();
     QString retval = popOutputBuffer();
     Q_ASSERT(m_buffers.isEmpty());
@@ -941,22 +951,46 @@ static bool copyImage(const QString &href, const QString &docDataDir,
     return true;
 }
 
+bool QtXmlToSphinx::copyImage(const QString &href) const
+{
+    QString errorMessage;
+    const bool result =
+        ::copyImage(href, m_generator->docDataDir(), m_context,
+                    m_generator->outputDirectory(), &errorMessage);
+    if (!result)
+        qCWarning(lcShiboken, "%s", qPrintable(errorMessage));
+    return result;
+}
+
 void QtXmlToSphinx::handleImageTag(QXmlStreamReader& reader)
 {
-    QXmlStreamReader::TokenType token = reader.tokenType();
-    if (token == QXmlStreamReader::StartElement) {
-        QString href = reader.attributes().value(QLatin1String("href")).toString();
-        QString errorMessage;
-        if (!copyImage(href,m_generator->docDataDir(), m_context,
-                       m_generator->outputDirectory(), &errorMessage)) {
-            qCWarning(lcShiboken, "%s", qPrintable(errorMessage));
-        }
+    if (reader.tokenType() != QXmlStreamReader::StartElement)
+        return;
+    const QString href = reader.attributes().value(QLatin1String("href")).toString();
+    if (copyImage(href))
+        m_output << INDENT << ".. image:: " <<  href << endl << endl;
+}
 
-        if (reader.name() == QLatin1String("image"))
-            m_output << INDENT << ".. image:: " <<  href << endl << endl;
-        else
-            m_output << ".. image:: " << href << ' ';
-    }
+void QtXmlToSphinx::handleInlineImageTag(QXmlStreamReader& reader)
+{
+    if (reader.tokenType() != QXmlStreamReader::StartElement)
+        return;
+    const QString href = reader.attributes().value(QLatin1String("href")).toString();
+    if (!copyImage(href))
+        return;
+    // Handle inline images by substitution references. Insert a unique tag
+    // enclosed by '|' and define it further down. Determine tag from the base
+    //file name with number.
+    QString tag = href;
+    int pos = tag.lastIndexOf(QLatin1Char('/'));
+    if (pos != -1)
+        tag.remove(0, pos + 1);
+    pos = tag.indexOf(QLatin1Char('.'));
+    if (pos != -1)
+        tag.truncate(pos);
+    tag += QString::number(m_inlineImages.size() + 1);
+    m_inlineImages.append(InlineImage{tag, href});
+    m_output << '|' << tag << '|' << ' ';
 }
 
 void QtXmlToSphinx::handleRawTag(QXmlStreamReader& reader)
diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h
index 1977f3019..af26b7fab 100644
--- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h
+++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h
@@ -49,6 +49,12 @@ class QtDocGenerator;
 class QtXmlToSphinx
 {
 public:
+    struct InlineImage
+    {
+        QString tag;
+        QString href;
+    };
+
     struct TableCell
     {
         short rowSpan;
@@ -127,6 +133,7 @@ private:
     void handleDotsTag(QXmlStreamReader& reader);
     void handleLinkTag(QXmlStreamReader& reader);
     void handleImageTag(QXmlStreamReader& reader);
+    void handleInlineImageTag(QXmlStreamReader& reader);
     void handleListTag(QXmlStreamReader& reader);
     void handleTermTag(QXmlStreamReader& reader);
     void handleSuperScriptTag(QXmlStreamReader& reader);
@@ -168,6 +175,7 @@ private:
     bool m_insideItalic;
     QString m_lastTagName;
     QString m_opened_anchor;
+    QVector<InlineImage> m_inlineImages;
 
     QString readFromLocations(const QStringList &locations, const QString &path,
                               const QString &identifier, QString *errorMessage);
@@ -176,6 +184,7 @@ private:
     void pushOutputBuffer();
     QString popOutputBuffer();
     void writeTable(Table& table);
+    bool copyImage(const QString &href) const;
 };
 
 inline QTextStream& operator<<(QTextStream& s, const QtXmlToSphinx& xmlToSphinx)