You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
583 lines
18 KiB
583 lines
18 KiB
/////////////////////////////////////////////////////////////////////////////////// |
|
// Copyright (C) 2026 Jon Beniston, M7RCE <jon@beniston.com> // |
|
// Some code by AI // |
|
// // |
|
// This program is free software; you can redistribute it and/or modify // |
|
// it under the terms of the GNU General Public License as published by // |
|
// the Free Software Foundation as version 3 of the License, or // |
|
// (at your option) any later version. // |
|
// // |
|
// This program is distributed in the hope that it will be useful, // |
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of // |
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // |
|
// GNU General Public License V3 for more details. // |
|
// // |
|
// You should have received a copy of the GNU General Public License // |
|
// along with this program. If not, see <http://www.gnu.org/licenses/>. // |
|
/////////////////////////////////////////////////////////////////////////////////// |
|
|
|
#include <QDebug> |
|
#include <QDir> |
|
#include <QFile> |
|
#include <QJsonArray> |
|
#include <QRegularExpression> |
|
|
|
#include "maincore.h" |
|
#include "device/deviceenumerator.h" |
|
#include "plugin/pluginmanager.h" |
|
#include "plugin/plugininterface.h" |
|
|
|
#include "mcpdocs.h" |
|
|
|
MCPDocs::MCPDocs() : |
|
m_loaded(false) |
|
{ |
|
} |
|
|
|
const QList<MCPDocs::Doc>& MCPDocs::list() |
|
{ |
|
load(); |
|
return m_docs; |
|
} |
|
|
|
const MCPDocs::Doc *MCPDocs::find(const QString& typeIn, const QString& kindIn) |
|
{ |
|
load(); |
|
QString type = normalize(typeIn); |
|
QString kind = kindIn.trimmed().toLower(); |
|
|
|
// Exact id first, then displayed name, then readme title, so that "ADS-B" or "RTL-SDR" also resolve |
|
for (int pass = 0; pass < 3; pass++) |
|
{ |
|
for (const Doc& doc : m_docs) |
|
{ |
|
if (!kind.isEmpty() && (doc.kind != kind)) { |
|
continue; |
|
} |
|
|
|
bool hit; |
|
|
|
if (pass == 0) |
|
{ |
|
hit = normalize(doc.id) == type; |
|
|
|
for (const QString& alias : doc.aliases) { |
|
hit = hit || (normalize(alias) == type); |
|
} |
|
} |
|
else if (pass == 1) |
|
{ |
|
hit = normalize(doc.name) == type; |
|
} |
|
else |
|
{ |
|
hit = normalize(doc.title).startsWith(type); |
|
} |
|
|
|
if (hit) { |
|
return &doc; |
|
} |
|
} |
|
} |
|
|
|
return nullptr; |
|
} |
|
|
|
QString MCPDocs::text(const Doc& doc, const QString& section) |
|
{ |
|
QString markdown = toMarkdown(readFile(doc.path)); |
|
|
|
if (section.trimmed().isEmpty()) { |
|
return markdown; |
|
} |
|
|
|
// Return the section whose heading contains the requested text, up to the next heading |
|
// of the same or a higher level |
|
QString wanted = section.trimmed().toLower(); |
|
QStringList lines = markdown.split('\n'); |
|
int start = -1; |
|
int startLevel = 0; |
|
|
|
for (int i = 0; i < lines.size(); i++) |
|
{ |
|
int level; |
|
QString heading = headingText(lines[i], level); |
|
|
|
if (level == 0) { |
|
continue; |
|
} |
|
|
|
if (start < 0) |
|
{ |
|
if (heading.toLower().contains(wanted)) |
|
{ |
|
start = i; |
|
startLevel = level; |
|
} |
|
} |
|
else if (level <= startLevel) |
|
{ |
|
return lines.mid(start, i - start).join('\n').trimmed(); |
|
} |
|
} |
|
|
|
if (start >= 0) { |
|
return lines.mid(start).join('\n').trimmed(); |
|
} |
|
|
|
return QString(); |
|
} |
|
|
|
QJsonObject MCPDocs::index() |
|
{ |
|
load(); |
|
QJsonArray docs; |
|
|
|
for (const Doc& doc : m_docs) |
|
{ |
|
QJsonObject d; |
|
d["kind"] = doc.kind; |
|
d["id"] = doc.id; |
|
|
|
if (!doc.aliases.isEmpty()) { |
|
d["aliases"] = QJsonArray::fromStringList(doc.aliases); |
|
} |
|
|
|
if (!doc.direction.isEmpty()) { |
|
d["direction"] = doc.direction; |
|
} |
|
|
|
d["name"] = doc.name; |
|
d["title"] = doc.title; |
|
d["uri"] = uri(doc); |
|
d["headings"] = QJsonArray::fromStringList(doc.headings); |
|
docs.append(d); |
|
} |
|
|
|
QJsonObject result; |
|
result["count"] = docs.count(); |
|
result["docs"] = docs; |
|
return result; |
|
} |
|
|
|
// Hand written guide compiled in beside the plugin readmes |
|
QString MCPDocs::guide() |
|
{ |
|
QString text = readFile(":/mcpdocs/bandguide.md"); |
|
|
|
if (text.isEmpty()) { |
|
return QString("The receiving guide is not available in this build."); |
|
} |
|
|
|
return text; |
|
} |
|
|
|
QStringList MCPDocs::unmatchedReadmes() |
|
{ |
|
load(); |
|
QStringList result; |
|
|
|
for (const Readme& readme : m_readmes) |
|
{ |
|
if (!readme.used) { |
|
result.append(readme.group + "/" + readme.dir); |
|
} |
|
} |
|
|
|
return result; |
|
} |
|
|
|
// --------------------------------------------------------------------------- |
|
|
|
void MCPDocs::load() |
|
{ |
|
if (m_loaded) { |
|
return; |
|
} |
|
|
|
m_loaded = true; |
|
scanReadmes(); |
|
|
|
PluginManager *pluginManager = MainCore::instance()->getPluginManager(); |
|
|
|
if (!pluginManager) { |
|
return; |
|
} |
|
|
|
for (const auto& reg : *pluginManager->getRxChannelRegistrations()) { |
|
addDoc("channel", reg.m_channelId, "rx", reg.m_channelIdURI, reg.m_plugin->getPluginDescriptor().displayedName, {"channelrx"}, reg.m_plugin); |
|
} |
|
for (const auto& reg : *pluginManager->getTxChannelRegistrations()) { |
|
addDoc("channel", reg.m_channelId, "tx", reg.m_channelIdURI, reg.m_plugin->getPluginDescriptor().displayedName, {"channeltx"}, reg.m_plugin); |
|
} |
|
for (const auto& reg : *pluginManager->getMIMOChannelRegistrations()) { |
|
addDoc("channel", reg.m_channelId, "mimo", reg.m_channelIdURI, reg.m_plugin->getPluginDescriptor().displayedName, {"channelmimo"}, reg.m_plugin); |
|
} |
|
for (const auto& reg : pluginManager->getSourceDeviceRegistrations()) { |
|
addDoc("device", reg.m_deviceHardwareId, "rx", reg.m_deviceId, reg.m_plugin->getPluginDescriptor().displayedName, {"samplesource"}, reg.m_plugin); |
|
} |
|
for (const auto& reg : pluginManager->getSinkDeviceRegistrations()) { |
|
addDoc("device", reg.m_deviceHardwareId, "tx", reg.m_deviceId, reg.m_plugin->getPluginDescriptor().displayedName, {"samplesink"}, reg.m_plugin); |
|
} |
|
for (const auto& reg : pluginManager->getMIMODeviceRegistrations()) { |
|
addDoc("device", reg.m_deviceHardwareId, "mimo", reg.m_deviceId, reg.m_plugin->getPluginDescriptor().displayedName, {"samplemimo"}, reg.m_plugin); |
|
} |
|
for (const auto& reg : *pluginManager->getFeatureRegistrations()) { |
|
addDoc("feature", reg.m_featureId, "", reg.m_featureIdURI, reg.m_plugin->getPluginDescriptor().displayedName, {"feature"}, reg.m_plugin); |
|
} |
|
|
|
applyEnumeratedDeviceIds(); |
|
addGuiDocs(); |
|
|
|
qDebug("MCPDocs::load: %d readmes, %d matched to plugins, unmatched: %s", |
|
(int) m_readmes.size(), (int) m_docs.size(), qPrintable(unmatchedReadmes().join(", "))); |
|
} |
|
|
|
// Pages of the GUI's own, compiled in under :/mcpdocs/gui by the CMake list beside this one. |
|
// The spectrum display is the one that matters most: its settings are the only ones a client |
|
// changes that no plugin readme explains |
|
void MCPDocs::addGuiDocs() |
|
{ |
|
struct Page { const char *id; const char *name; const char *file; QStringList aliases; }; |
|
|
|
static const QList<Page> pages = { |
|
{"spectrum", "Spectrum display", "spectrum.md", {"GLSpectrum", "spectrum display", "spectrum component"}}, |
|
{"spectrummarkers", "Spectrum markers", "spectrummarkers.md", {"markers"}}, |
|
{"spectrummeasurements", "Spectrum measurements", "spectrummeasurements.md", {"measurements"}}, |
|
{"spectrumcalibration", "Spectrum calibration", "spectrumcalibration.md", {"calibration"}}, |
|
{"mainspectrum", "Main spectrum window", "mainspectrum.md", {}}, |
|
{"audio", "Audio management", "audio.md", {}}, |
|
{"configurations", "Configurations", "configurations.md", {}}, |
|
{"deviceuserargs", "Device user arguments", "deviceuserargs.md", {}}, |
|
{"transverter", "Transverter dialog", "transverterdialog.md", {}} |
|
}; |
|
|
|
for (const Page& page : pages) |
|
{ |
|
QString path = QString(":/mcpdocs/gui/%1").arg(page.file); |
|
|
|
if (!QFile::exists(path)) { |
|
continue; // not in this build |
|
} |
|
|
|
QString markdown = toMarkdown(readFile(path)); |
|
Doc doc; |
|
doc.kind = "gui"; |
|
doc.id = page.id; |
|
doc.aliases = page.aliases; |
|
doc.name = page.name; |
|
doc.title = page.name; |
|
doc.path = path; |
|
doc.headings = extractHeadings(markdown); |
|
doc.plugin = nullptr; |
|
|
|
// The page's own first heading, when it has one |
|
for (const QString& line : markdown.split('\n')) |
|
{ |
|
int level; |
|
QString heading = headingText(line, level); |
|
|
|
if (level > 0) |
|
{ |
|
doc.title = heading; |
|
break; |
|
} |
|
} |
|
|
|
m_docs.append(doc); |
|
} |
|
} |
|
|
|
void MCPDocs::scanReadmes() |
|
{ |
|
QDir root(":/mcpdocs"); |
|
|
|
for (const QString& group : root.entryList(QDir::Dirs | QDir::NoDotAndDotDot)) |
|
{ |
|
QDir groupDir(root.filePath(group)); |
|
|
|
for (const QString& dir : groupDir.entryList(QDir::Dirs | QDir::NoDotAndDotDot)) |
|
{ |
|
QString path = groupDir.filePath(dir) + "/readme.md"; |
|
|
|
if (!QFile::exists(path)) { |
|
continue; |
|
} |
|
|
|
Readme readme; |
|
readme.group = group; |
|
readme.dir = dir; |
|
readme.path = path; |
|
readme.used = false; |
|
|
|
// Title is the first heading |
|
for (const QString& line : readFile(path).split('\n')) |
|
{ |
|
int level; |
|
QString heading = headingText(line, level); |
|
|
|
if (level > 0) |
|
{ |
|
readme.title = heading; |
|
break; |
|
} |
|
} |
|
|
|
m_readmes.append(readme); |
|
} |
|
} |
|
} |
|
|
|
// The hardware id a device plugin registers with can differ from the one it enumerates devices under, |
|
// and the enumerated one is what list_available_devices, set_device and describe_settings use. |
|
// Make that the canonical id and keep the registration id as an alias. |
|
void MCPDocs::applyEnumeratedDeviceIds() |
|
{ |
|
DeviceEnumerator *enumerator = DeviceEnumerator::instance(); |
|
|
|
auto apply = [this](const QString& direction, const PluginInterface::SamplingDevice *device, PluginInterface *plugin) |
|
{ |
|
for (Doc& doc : m_docs) |
|
{ |
|
if ((doc.kind != "device") || (doc.direction != direction) || (doc.plugin != plugin)) { |
|
continue; |
|
} |
|
|
|
if (doc.id != device->hardwareId) |
|
{ |
|
if (!doc.aliases.contains(doc.id)) { |
|
doc.aliases.append(doc.id); |
|
} |
|
|
|
doc.aliases.removeAll(device->hardwareId); |
|
doc.id = device->hardwareId; |
|
} |
|
} |
|
}; |
|
|
|
for (int i = 0; i < enumerator->getNbRxSamplingDevices(); i++) { |
|
apply("rx", enumerator->getRxSamplingDevice(i), enumerator->getRxPluginInterface(i)); |
|
} |
|
for (int i = 0; i < enumerator->getNbTxSamplingDevices(); i++) { |
|
apply("tx", enumerator->getTxSamplingDevice(i), enumerator->getTxPluginInterface(i)); |
|
} |
|
for (int i = 0; i < enumerator->getNbMIMOSamplingDevices(); i++) { |
|
apply("mimo", enumerator->getMIMOSamplingDevice(i), enumerator->getMIMOPluginInterface(i)); |
|
} |
|
} |
|
|
|
void MCPDocs::addDoc(const QString& kind, const QString& id, const QString& direction, const QString& uri, |
|
const QString& displayedName, const QStringList& groups, PluginInterface *plugin) |
|
{ |
|
// Several device plugins register the same hardware id (e.g. for different device instances) |
|
for (const Doc& existing : m_docs) |
|
{ |
|
if ((existing.kind == kind) && (existing.id == id) && (existing.direction == direction)) { |
|
return; |
|
} |
|
} |
|
|
|
const Readme *readme = match(groups, id, uri, displayedName); |
|
|
|
if (!readme) |
|
{ |
|
qDebug("MCPDocs::addDoc: no readme for %s %s (%s)", qPrintable(kind), qPrintable(id), qPrintable(displayedName)); |
|
return; |
|
} |
|
|
|
Doc doc; |
|
doc.kind = kind; |
|
doc.id = id; |
|
doc.direction = direction; |
|
doc.name = displayedName; |
|
doc.title = readme->title; |
|
doc.path = readme->path; |
|
doc.headings = extractHeadings(toMarkdown(readFile(readme->path))); |
|
doc.plugin = plugin; |
|
m_docs.append(doc); |
|
} |
|
|
|
// Directory names and ids differ (demodadsb vs ADSBDemod, rtlsdr vs RTLSDR, chanalyzer vs ChannelAnalyzer), |
|
// so compare normalized forms with the demod/mod affixes removed, then fall back to the readme title. |
|
const MCPDocs::Readme *MCPDocs::match(const QStringList& groups, const QString& id, const QString& uri, const QString& displayedName) |
|
{ |
|
// Plugins whose directory, id and title all differ |
|
static const QMap<QString, QString> overrides = { |
|
{"ChannelAnalyzer", "chanalyzer"}, |
|
{"IEEE_802_15_4_Demod", "demod802.15.4"}, |
|
{"IEEE_802_15_4_Mod", "mod802.15.4"}, |
|
}; |
|
|
|
QStringList idCandidates; |
|
QString normId = normalize(id); |
|
idCandidates.append(normId); |
|
idCandidates.append(normalize(uri.section('.', -1))); |
|
|
|
if (overrides.contains(id)) { |
|
idCandidates.prepend(normalize(overrides[id])); |
|
} |
|
|
|
// Device plugins share a hardware id between input and output and live in |
|
// "<id>input" / "<id>output" directories |
|
idCandidates.append(normId + "input"); |
|
idCandidates.append(normId + "output"); |
|
|
|
for (const QString affix : {"demod", "mod"}) |
|
{ |
|
if (normId.endsWith(affix) && (normId.size() > affix.size())) { |
|
idCandidates.append(normId.left(normId.size() - affix.size())); |
|
} |
|
} |
|
|
|
auto dirCandidates = [](const QString& dir) |
|
{ |
|
QStringList result; |
|
QString normDir = normalize(dir); |
|
result.append(normDir); |
|
|
|
for (const QString affix : {"demod", "mod"}) |
|
{ |
|
if (normDir.startsWith(affix) && (normDir.size() > affix.size())) { |
|
result.append(normDir.mid(affix.size())); |
|
} |
|
} |
|
|
|
return result; |
|
}; |
|
|
|
// Pass 1: names |
|
for (Readme& readme : m_readmes) |
|
{ |
|
if (!groups.contains(readme.group)) { |
|
continue; |
|
} |
|
|
|
for (const QString& d : dirCandidates(readme.dir)) |
|
{ |
|
if (idCandidates.contains(d)) |
|
{ |
|
readme.used = true; |
|
return &readme; |
|
} |
|
} |
|
} |
|
|
|
// Pass 2: displayed name against the readme title, e.g. "ADS-B Demodulator" and "ADS-B demodulator plugin" |
|
QString normName = normalize(displayedName); |
|
|
|
if (!normName.isEmpty()) |
|
{ |
|
for (Readme& readme : m_readmes) |
|
{ |
|
if (!groups.contains(readme.group)) { |
|
continue; |
|
} |
|
|
|
QString normTitle = normalize(readme.title); |
|
|
|
if (normTitle.startsWith(normName) || normName.startsWith(normTitle)) |
|
{ |
|
readme.used = true; |
|
return &readme; |
|
} |
|
} |
|
} |
|
|
|
return nullptr; |
|
} |
|
|
|
QString MCPDocs::normalize(const QString& s) |
|
{ |
|
QString result; |
|
|
|
for (const QChar& c : s.toLower()) |
|
{ |
|
if (c.isLetterOrNumber()) { |
|
result.append(c); |
|
} |
|
} |
|
|
|
return result; |
|
} |
|
|
|
QString MCPDocs::readFile(const QString& path) |
|
{ |
|
QFile file(path); |
|
|
|
if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) { |
|
return QString(); |
|
} |
|
|
|
return QString::fromUtf8(file.readAll()); |
|
} |
|
|
|
// Readmes mix HTML headings with markdown. Normalize headings to markdown and drop images, |
|
// which cannot be served to the model. |
|
QString MCPDocs::toMarkdown(const QString& raw) |
|
{ |
|
static const QRegularExpression htmlHeading("^\\s*<h([1-6])>(.*?)</h\\1>\\s*$"); |
|
static const QRegularExpression image("^\\s*!\\[[^\\]]*\\]\\([^)]*\\)\\s*$"); |
|
static const QRegularExpression htmlImage("^\\s*<img\\b[^>]*>\\s*$", QRegularExpression::CaseInsensitiveOption); |
|
QStringList out; |
|
|
|
for (const QString& line : raw.split('\n')) |
|
{ |
|
QRegularExpressionMatch m = htmlHeading.match(line); |
|
|
|
if (m.hasMatch()) |
|
{ |
|
out.append(QString(m.captured(1).toInt(), '#') + " " + m.captured(2).trimmed()); |
|
continue; |
|
} |
|
|
|
if (image.match(line).hasMatch() || htmlImage.match(line).hasMatch()) { |
|
continue; |
|
} |
|
|
|
out.append(line.endsWith('\r') ? line.chopped(1) : line); |
|
} |
|
|
|
return out.join('\n'); |
|
} |
|
|
|
// Returns the heading text of a markdown heading line and its level, or level 0 for other lines |
|
QString MCPDocs::headingText(const QString& line, int& level) |
|
{ |
|
static const QRegularExpression mdHeading("^(#{1,6})\\s+(.*?)\\s*#*\\s*$"); |
|
static const QRegularExpression htmlHeading("^\\s*<h([1-6])>(.*?)</h\\1>\\s*$"); |
|
QRegularExpressionMatch m = mdHeading.match(line); |
|
|
|
if (m.hasMatch()) |
|
{ |
|
level = m.captured(1).size(); |
|
return m.captured(2); |
|
} |
|
|
|
m = htmlHeading.match(line); |
|
|
|
if (m.hasMatch()) |
|
{ |
|
level = m.captured(1).toInt(); |
|
return m.captured(2).trimmed(); |
|
} |
|
|
|
level = 0; |
|
return QString(); |
|
} |
|
|
|
QStringList MCPDocs::extractHeadings(const QString& markdown) |
|
{ |
|
QStringList headings; |
|
|
|
for (const QString& line : markdown.split('\n')) |
|
{ |
|
int level; |
|
QString heading = headingText(line, level); |
|
|
|
if (level > 0) { |
|
headings.append(QString(level, '#') + " " + heading); |
|
} |
|
} |
|
|
|
return headings; |
|
}
|
|
|