Autogenerated docs: operators don't seem clickable in overload pages #399

anarthal · 2025-01-29T10:43:39Z

I'm opening this as a continuation of cppalliance/mrdocs#826. I'm generating docs using MrDocs (this is, Doxygen comments transformed to asciidoc files with MrDocs, then transformed to HTML with Antora. When an operator is overloaded (e.g. copy/move assignment), it generates an overload page that includes links to each of the individual overloads. The link spans the entire function name (that is, operator=), but only the = part of the name is formatted as a link (as opposed to the entire operator=). There seems to be some contention with syntax highlighting, where highlight.js identifies operator as a keyword, overriding the link style.

The impact is that links seem to be not clickable.

I'll provide as much info as I can. Please feel free to request any missing details:

What it's rendered:

What should ideally be rendered (old toolchain - notice how the link spans the entire operator=):

Generated HTML:

<!DOCTYPE html>
<html lang="en">
  <head>
        <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>boost::mysql::row::operator&equals; :: Boost.MySQL documentation</title>
  <link rel="canonical" href="https://test.com/mysql/reference/boost/mysql/row/operator_assign.html">
  <meta name="generator" content="Antora 3.1.10">
    <link rel="stylesheet" href="../../../../../_/css/boostlook.css">
    <link rel="stylesheet" href="../../../../../_/css/site.css">
    <link rel="stylesheet" href="../../../../../_/css/vendor/tabs.css">
    <script>var uiRootPath = '../../../../../_'</script>
<link rel="icon" href="../../../../../_/img/favicons/favicon.ico" type="image/x-icon">
    <!-- Favicon configuration -->
    <link rel="apple-touch-icon" sizes="180x180" href="../../../../../_/img/favicons/apple-touch-icon.png">
    <link rel="icon" type="image/png" sizes="32x32" href="../../../../../_/img/favicons/favicon-32x32.png">
    <link rel="icon" type="image/png" sizes="16x16" href="../../../../../_/img/favicons/favicon-16x16.png">
    <link rel="manifest" href="../../../../../_/img/favicons/site.webmanifest">
    <link rel="shortcut icon" href="../../../../../_/img/favicons/favicon.ico">
  </head>
  <body class="article toc2 toc-left">
    <div class="boostlook">
  <div id="header">
    <div id="toc" class="nav-container toc2" data-component="mysql" data-version="">
  <aside class="nav">
    <button class="nav-close"></button>
    <div class="panels">
      <div class="nav-panel-menu is-active" data-panel="menu">
  <nav class="nav-menu">
      <h3 class="title"><a href="../../../../index.html">Boost.MySQL</a></h3>
      <ul class="nav-list">
        <ul class="nav-list">
        <li class="" data-depth="1">
            <a class="nav-link" href="../../../../index.html">Introduction</a>
        </li>
              <li class="" data-depth="1">
            <a class="nav-link" href="../../../../overview.html">Overview</a>
        </li>
              <li class="" data-depth="1">
            <a class="nav-link" href="../../../index.html">Reference</a>
        </li>
        </ul>
  </ul>
  </nav>
</div>
    </div>
  </aside>
</div>
</div>
  <div id="content">
    <article class="doc max-width-reset">
  <div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<nav class="breadcrumbs" aria-label="breadcrumbs">
  <ul>
    <li>
      <a href="../../../../index.html" aria-label="Home: Boost.MySQL">
        <svg xmlns="http://www.w3.org/2000/svg" width="1rem" height="1rem" viewBox="0 -960 960 960" fill="#000000" aria-hidden="true"><path d="M160-120v-480l320-240 320 240v480H560v-280H400v280H160Z"/></svg>
      </a>
    </li>
    <li><a href="operator_assign.html"><a href="../../../boost.html">boost</a>::<a href="../../../boost/mysql.html">mysql</a>::<a href="../../../boost/mysql/row.html">row</a>::operator&equals;</a></li>
  </ul>
</nav>
<div class="spirit-nav">
</div>
</div>
    <h1 class="page"><a href="../../../boost.html">boost</a>::<a href="../../../boost/mysql.html">mysql</a>::<a href="../../../boost/mysql/row.html">row</a>::operator&equals;</h1>
  <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Copy assignment&period;</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_synopsis"><a class="anchor" href="#_synopsis"></a>Synopsis</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Declared in <code>&lt;<a href="https://github.com/boostorg/mysql/blob/master/include/boost/mysql/row.hpp#L111">boost&sol;mysql&sol;row&period;hpp</a>&gt;</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp">constexpr
<a href="../row.html" class="xref page">row</a>&amp;
<a href="operator_assign-08.html" class="xref page">operator&equals;</a>(<a href="../row.html" class="xref page">row</a> const&amp; other) = default;</code></pre>
</div>
</div>
<div class="paragraph">
<p><span class="small"><a href="operator_assign-08.html" class="xref page"><em>» more&#8230;&#8203;</em></a></span></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp">constexpr
<a href="../row.html" class="xref page">row</a>&amp;
<a href="operator_assign-05.html" class="xref page">operator&equals;</a>(<a href="../row.html" class="xref page">row</a>&amp;&amp; other) = default;</code></pre>
</div>
</div>
<div class="paragraph">
<p><span class="small"><a href="operator_assign-05.html" class="xref page"><em>» more&#8230;&#8203;</em></a></span></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-cpp hljs" data-lang="cpp"><a href="../row.html" class="xref page">row</a>&amp;
<a href="operator_assign-0a.html" class="xref page">operator&equals;</a>(<a href="../row_view.html" class="xref page">row&lowbar;view</a> r);</code></pre>
</div>
</div>
<div class="paragraph">
<p><span class="small"><a href="operator_assign-0a.html" class="xref page"><em>» more&#8230;&#8203;</em></a></span></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description"><a class="anchor" href="#_description"></a>Description</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_exception_safety"><a class="anchor" href="#_exception_safety"></a>Exception safety</h3>
<div class="paragraph">
<p>Basic guarantee&period; Internal allocations may throw&period;</p>
</div>
</div>
<div class="sect2">
<h3 id="_object_lifetimes"><a class="anchor" href="#_object_lifetimes"></a>Object lifetimes</h3>
<div class="paragraph">
<p><code>&ast;this</code> lifetime will be independent of <code>other</code>&apos;s&period; Iterators and references (including <a href="../row_view.html" class="xref page">row&lowbar;view</a>&apos;s and <a href="../field_view.html" class="xref page">field&lowbar;view</a>&apos;s) to elements in <code>&ast;this</code> are invalidated&period;</p>
</div>
</div>
<div class="sect2">
<h3 id="_complexity"><a class="anchor" href="#_complexity"></a>Complexity</h3>
<div class="paragraph">
<p>Linear on <code>this&hyphen;&gt;size()</code> and <code>other&period;size()</code>&period;</p>
</div>
<div class="paragraph">
<p><span class="small">Created with <a href="https://www.mrdocs.com">MrDocs</a></span></p>
</div>
</div>
</div>
</div>
  <div class="edit-this-page">
  </div>
  </article>
</div>
  <div id="footer">
  <script id="site-script" src="../../../../../_/js/site.js" data-ui-root-path="../../../../../_"></script>
<script async src="../../../../../_/js/vendor/highlight.js"></script>
<script async src="../../../../../_/js/vendor/tabs.js" data-sync-storage-key="preferred-tab"></script>
</div>
</div>
  </body>
</html>

Thanks,
Ruben.

The text was updated successfully, but these errors were encountered:

anarthal · 2025-01-29T18:33:12Z

I found another issue that might be related to this, too. Constructors in overload pages are sometimes highlighted in another color. These constructors actually contain links to their definitions, so they probably should look like links. The current coloring makes them look like broken links.

For instance:

Live URL: https://anarthal.github.io/mysql-mrdocs-v1/mysql/reference/boost/mysql/any_address/2constructor.html

Note that all any_address links (even the ones in red) contain valid links.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Autogenerated docs: operators don't seem clickable in overload pages #399

Autogenerated docs: operators don't seem clickable in overload pages #399

anarthal commented Jan 29, 2025

anarthal commented Jan 29, 2025

Autogenerated docs: operators don't seem clickable in overload pages #399

Autogenerated docs: operators don't seem clickable in overload pages #399

Comments

anarthal commented Jan 29, 2025

anarthal commented Jan 29, 2025