diff options
author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2018-05-02 10:21:55 +0200 |
---|---|---|
committer | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2018-05-02 13:27:38 +0000 |
commit | d5581049f8789eae86e91372f34ec8ed794272aa (patch) | |
tree | bf805917df650283ed0238b60c712779c02b51f2 /sources/shiboken2/generator | |
parent | d90fcd0f0f0e1279676714f6835fd9ae3c1258db (diff) |
Add option to create additional documentation
Add an option taking a list of files under the webxml directory
that are run though the Sphinx converter to create .rst files.
This can be used for tutorials and example descriptions.
Task-number: PYSIDE-363
Change-Id: Ifa6df32517a2b336cd3f755523947d70c5c24f2e
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
Diffstat (limited to 'sources/shiboken2/generator')
-rw-r--r-- | sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp | 96 | ||||
-rw-r--r-- | sources/shiboken2/generator/qtdoc/qtdocgenerator.h | 9 |
2 files changed, 101 insertions, 4 deletions
diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp index cefce32fa..7b9f25369 100644 --- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp +++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.cpp @@ -45,6 +45,8 @@ static Indentor INDENT; +static inline QString additionalDocumentationOption() { return QStringLiteral("additional-documentation"); } + static bool shouldSkip(const AbstractMetaFunction* func) { // Constructors go to separate section @@ -1119,6 +1121,26 @@ void QtXmlToSphinx::handleQuoteFileTag(QXmlStreamReader& reader) } } +bool QtXmlToSphinx::convertToRst(QtDocGenerator *generator, + const QString &sourceFileName, + const QString &targetFileName, + const QString &context, QString *errorMessage) +{ + QFile sourceFile(sourceFileName); + if (!sourceFile.open(QIODevice::ReadOnly | QIODevice::Text)) { + if (errorMessage) + *errorMessage = FileOut::msgCannotOpenForReading(sourceFile); + return false; + } + const QString doc = QString::fromUtf8(sourceFile.readAll()); + sourceFile.close(); + + FileOut targetFile(targetFileName); + QtXmlToSphinx x(generator, doc, context); + targetFile.stream << x; + return targetFile.done(errorMessage) != FileOut::Failure; +} + void QtXmlToSphinx::Table::normalize() { if (m_normalized || isEmpty()) @@ -1910,9 +1932,15 @@ static void writeFancyToc(QTextStream& s, const QStringList& items, int cols = 4 bool QtDocGenerator::finishGeneration() { - if (classes().isEmpty()) - return true; + if (!classes().isEmpty()) + writeModuleDocumentation(); + if (!m_additionalDocumentationList.isEmpty()) + writeAdditionalDocumentation(); + return true; +} +void QtDocGenerator::writeModuleDocumentation() +{ QMap<QString, QStringList>::iterator it = m_packages.begin(); for (; it != m_packages.end(); ++it) { QString key = it.key(); @@ -1984,7 +2012,63 @@ bool QtDocGenerator::finishGeneration() } } } - return true; +} + +static inline QString msgNonExistentAdditionalDocFile(const QString &dir, + const QString &fileName) +{ + const QString result = QLatin1Char('"') + fileName + + QLatin1String("\" does not exist in ") + + QDir::toNativeSeparators(dir) + QLatin1Char('.'); + return result; +} + +void QtDocGenerator::writeAdditionalDocumentation() +{ + QFile additionalDocumentationFile(m_additionalDocumentationList); + if (!additionalDocumentationFile.open(QIODevice::ReadOnly | QIODevice::Text)) { + qCWarning(lcShiboken, "%s", + qPrintable(FileOut::msgCannotOpenForReading(additionalDocumentationFile))); + return; + } + const QByteArray contents = additionalDocumentationFile.readAll(); + const QStringList lines = QFile::decodeName(contents).split(QLatin1Char('\n')); + QFileInfoList additionalDocFiles; + additionalDocFiles.reserve(lines.size()); + for (const QString &lineIn : lines) { + const QString line = lineIn.trimmed(); + if (!line.isEmpty() && !line.startsWith(QLatin1Char('#'))) { + QFileInfo fi(m_docDataDir + QLatin1Char('/') + line); + if (fi.isFile()) { + additionalDocFiles.append(fi); + } else { + qCWarning(lcShiboken, "%s", + qPrintable(msgNonExistentAdditionalDocFile(m_docDataDir, line))); + } + } + } + additionalDocumentationFile.close(); + + const QString rstPrefix = outputDirectory() + QLatin1Char('/'); + const QString rstSuffix = fileNameSuffix(); + + QString errorMessage; + int successCount = 0; + for (const QFileInfo &additionalDocFile : additionalDocFiles) { + const QString rstFileName = additionalDocFile.baseName() + rstSuffix; + const QString rstFile = rstPrefix + rstFileName; + if (QtXmlToSphinx::convertToRst(this, additionalDocFile.absoluteFilePath(), + rstFile, QString(), &errorMessage)) { + ++successCount; + qCDebug(lcShiboken).nospace().noquote() << __FUNCTION__ + << " converted " << additionalDocFile.fileName() + << ' ' << rstFileName; + } else { + qCWarning(lcShiboken, "%s", qPrintable(errorMessage)); + } + } + qCInfo(lcShiboken, "Created %d/%d additional documentation files.", + successCount, additionalDocFiles.size()); } bool QtDocGenerator::doSetup(const QMap<QString, QString>& args) @@ -2012,6 +2096,7 @@ bool QtDocGenerator::doSetup(const QMap<QString, QString>& args) m_docParser->setDocumentationDataDirectory(m_docDataDir); m_docParser->setLibrarySourceDirectory(m_libSourceDir); } + m_additionalDocumentationList = args.value(additionalDocumentationOption()); return true; } @@ -2029,6 +2114,9 @@ Generator::OptionDescriptions QtDocGenerator::options() const << qMakePair(QLatin1String("documentation-extra-sections-dir"), QLatin1String("Directory used to search for extra documentation sections")) << qMakePair(QLatin1String("library-source-dir"), - QLatin1String("Directory where library source code is located")); + QLatin1String("Directory where library source code is located")) + << qMakePair(additionalDocumentationOption(), + QLatin1String("List of additional XML files to be converted to .rst files\n" + "(for example, tutorials).")); } diff --git a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h index f7a627127..04d3a3e62 100644 --- a/sources/shiboken2/generator/qtdoc/qtdocgenerator.h +++ b/sources/shiboken2/generator/qtdoc/qtdocgenerator.h @@ -102,6 +102,12 @@ public: QtXmlToSphinx(QtDocGenerator* generator, const QString& doc, const QString& context = QString()); + static bool convertToRst(QtDocGenerator *generator, + const QString &sourceFileName, + const QString &targetFileName, + const QString &context = QString(), + QString *errorMessage = nullptr); + QString result() const { return m_result; @@ -254,6 +260,8 @@ private: bool writeInjectDocumentation(QTextStream& s, TypeSystem::DocModificationMode mode, const AbstractMetaClass* cppClass, const AbstractMetaFunction* func); void writeDocSnips(QTextStream &s, const CodeSnipList &codeSnips, TypeSystem::CodeSnipPosition position, TypeSystem::Language language); + void writeModuleDocumentation(); + void writeAdditionalDocumentation(); QString parseArgDocStyle(const AbstractMetaClass *cppClass, const AbstractMetaFunction *func); QString translateToPythonType(const AbstractMetaType *type, const AbstractMetaClass *cppClass); @@ -265,6 +273,7 @@ private: QStringList m_functionList; QMap<QString, QStringList> m_packages; DocParser* m_docParser; + QString m_additionalDocumentationList; }; #endif // DOCGENERATOR_H |