documentation/doxygen: omit filename in anchors to the page itself.

I'm already doing that for all links coming from the template
(crosslinks between member lists and detailed info, section heading
links etc.) but so far it wasn't done for links and references contained
in Doxygen comments themselves.

That not only makes the generated files smaller, especially when there's
a lot of cross-references with large namespace docs full of functions
and typedefs, but also makes the output consistent between 1.8.16 and
1.12, which is why I'm doing this in the first place.

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 0e688489c36b12ea408769d70bbd716dbfab196b..2418293164165146285d4a698a592aeaa31b171b 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -216,10 +216,18 @@ def parse_ref(state: State, element: ET.Element, add_inline_css_class: str = Non
     id = element.attrib['refid']
 
     if element.attrib['kindref'] == 'compound':
+        # TODO Unlike below, where the filename is dropped if it matches the
+        # current compound URL, here I don't really know what to do because
+        # <a> with empty href="" gets treated as a non-link by browsers.
         url = id + '.html'
     elif element.attrib['kindref'] == 'member':
         i = id.rindex('_1')
-        url = id[:i] + '.html' + '#' + id[i+2:]
+        url = id[:i] + '.html'
+        # There's no point in including the filename itself if linking to an
+        # anchor on the same page.
+        if url == state.current_compound_url:
+            url = ''
+        url += '#' + id[i+2:]
     else: # pragma: no cover
         logging.critical("{}: unknown <ref> kind {}".format(state.current, element.attrib['kindref']))
         assert False

diff --git a/documentation/test_doxygen/compound_listing/Directory/Sub/Class.h b/documentation/test_doxygen/compound_listing/Directory/Sub/Class.h
index 2e0f44860f19eaf7b62398ab4b9cdcd33351fa0c..f426f5382cd9e583d262c8aba7488cd7e124e9a3 100644 (file)
--- a/documentation/test_doxygen/compound_listing/Directory/Sub/Class.h
+++ b/documentation/test_doxygen/compound_listing/Directory/Sub/Class.h
@@ -19,6 +19,9 @@ Text.
 
 @section Class-section2 Section 2
 
+@ref Size "Link to this page shouldn't contain the filename" while
+@ref Directory::Var "link to another page should". Same with
+@ref Class-section "section references" vs @ref section-notoc "external pages".
 */
 class Class {
     public:

diff --git a/documentation/test_doxygen/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html b/documentation/test_doxygen/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html
index 28afc01b88db43a6f7c029aa0df4fa5e801ccdec..7fb8fac6852411eb6fef1c7cd3914bf547dbfba1 100644 (file)
--- a/documentation/test_doxygen/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html
+++ b/documentation/test_doxygen/compound_listing/classRoot_1_1Directory_1_1Sub_1_1Class.html
@@ -77,7 +77,7 @@
             </li>
           </ul>
         </nav>
-<section id="Class-section"><h2><a href="#Class-section">A section</a></h2><p>Text.</p><section id="Class-sub-section"><h3><a href="#Class-sub-section">Subsection</a></h3></section><section id="Class-sub-section2"><h3><a href="#Class-sub-section2">Subsection 2</a></h3><section id="Class-sub-section3"><h4><a href="#Class-sub-section3">Subsection 3</a></h4></section></section></section><section id="Class-section2"><h2><a href="#Class-section2">Section 2</a></h2></section>
+<section id="Class-section"><h2><a href="#Class-section">A section</a></h2><p>Text.</p><section id="Class-sub-section"><h3><a href="#Class-sub-section">Subsection</a></h3></section><section id="Class-sub-section2"><h3><a href="#Class-sub-section2">Subsection 2</a></h3><section id="Class-sub-section3"><h4><a href="#Class-sub-section3">Subsection 3</a></h4></section></section></section><section id="Class-section2"><h2><a href="#Class-section2">Section 2</a></h2><p><a href="#a912d8f1390853f90e0a9f19ec98771e6" class="m-doc">Link to this page shouldn&#x27;t contain the filename</a> while <a href="namespaceRoot_1_1Directory.html#acdc29819d61c01eed9c74242010a7601" class="m-doc">link to another page should</a>. Same with <a href="#Class-section" class="m-doc">section references</a> vs <a href="page-no-toc.html#section-notoc" class="m-doc">external pages</a>.</p></section>
         <section id="pub-types">
           <h2><a href="#pub-types">Public types</a></h2>
           <dl class="m-doc">

diff --git a/documentation/test_doxygen/contents_anchor_in_both_group_and_namespace/group__fizzbuzz.html b/documentation/test_doxygen/contents_anchor_in_both_group_and_namespace/group__fizzbuzz.html
index 8410f8f7aeef23b9ebf06305fbfd755de24005d9..e9d8ad8e4c2c6a72052d198f5d7d7352688b41cd 100644 (file)
--- a/documentation/test_doxygen/contents_anchor_in_both_group_and_namespace/group__fizzbuzz.html
+++ b/documentation/test_doxygen/contents_anchor_in_both_group_and_namespace/group__fizzbuzz.html
@@ -48,7 +48,7 @@
               <span class="m-doc-wrap-bumper">void </span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#ga809d062bb88fcd3bd6cf38be250aa348" class="m-doc-self">bar</a>(</span><span class="m-doc-wrap">)</span></span>
             </h3>
             <p>Bar.</p>
-<p><a name="this_anchor"></a> <a href="group__fizzbuzz.html#this_anchor" class="m-doc">More details</a></p>
+<p><a name="this_anchor"></a> <a href="#this_anchor" class="m-doc">More details</a></p>
           </div></section>
         </section>
       </div>

diff --git a/documentation/test_doxygen/contents_sections_headings/index.html b/documentation/test_doxygen/contents_sections_headings/index.html
index d1dbabb75bb22767149b5dca88bd4962e7048b8f..9165816a7df5d1141bbd595ae69954ec2bc58dd5 100644 (file)
--- a/documentation/test_doxygen/contents_sections_headings/index.html
+++ b/documentation/test_doxygen/contents_sections_headings/index.html
@@ -22,7 +22,7 @@
         <h1>
           My Project
         </h1>
-<section id="section"><h2><a href="#section">Page section</a></h2><p>Text.</p><section id="subsection"><h3><a href="#subsection">Page subsection</a></h3><p>Text!</p><section id="subsubsection"><h4><a href="#subsubsection">Sub-sub section</a></h4><p>Reference to <a href="index.html#subsection" class="m-doc">a page subsection</a> and <a href="index.html#subsubsection" class="m-doc">Sub-sub section</a>.</p></section></section></section>
+<section id="section"><h2><a href="#section">Page section</a></h2><p>Text.</p><section id="subsection"><h3><a href="#subsection">Page subsection</a></h3><p>Text!</p><section id="subsubsection"><h4><a href="#subsubsection">Sub-sub section</a></h4><p>Reference to <a href="#subsection" class="m-doc">a page subsection</a> and <a href="#subsubsection" class="m-doc">Sub-sub section</a>.</p></section></section></section>
       </div>
     </div>
   </div>

diff --git a/documentation/test_doxygen/contents_typography/index.html b/documentation/test_doxygen/contents_typography/index.html
index f1dccd1f87378bc5859b2a346c254d5a8e497f4a..2e49739a790604a24532694e845f255e464c7ce1 100644 (file)
--- a/documentation/test_doxygen/contents_typography/index.html
+++ b/documentation/test_doxygen/contents_typography/index.html
@@ -25,7 +25,7 @@
 <blockquote><p>A blockquote.</p></blockquote><p>Paragraph<br />with<br />explicit<br />line<br />breaks.</p><pre>Preformatted text.
 </pre><section id="section"><h2><a href="#section">Page section</a></h2><pre>Differently
   preformatted
-text.</pre><ul><li>Unordered</li><li>list</li><li>of<ul><li>nested</li><li>items</li></ul></li><li>and back</li></ul><ol><li>Ordered</li><li>list</li><li>of<ol><li>nested</li><li>items</li></ol></li><li>and back</li></ol><p><a name="an-anchor"></a> This is a <code>typewriter text</code>, <em>emphasis</em>, <strong>bold</strong>. <em>Emphasis with <code>typewriter</code> and <strong>bold</strong> nested.</em> <a href="http://google.com">http:/<wbr />/<wbr />google.com</a> and <a href="http://google.com">URL</a>. <small>Small <em>text</em>.</small> En-dash &ndash; and em-dash &mdash;. Reference to a <a href="index.html#section" class="m-doc">Page section</a>. Named reference with special characters in title: <a href="index.html#section" class="m-doc">&raquo; Warnings &laquo;</a>. Reference with escaped characters in&nbsp;title: <a href="index.html#an-anchor" class="m-doc">&lt;anchor&gt;</a>.</p><p>2<sup>nd</sup> is L<sub>&infin;</sub> &forall; &nabla; &pi; &real; &image; This costs no $, &euro;, &pound;, &yen; or &curren;.</p><p>Empty elements:</p><pre></pre><hr/><p>Above is a horizontal line.</p></section>
+text.</pre><ul><li>Unordered</li><li>list</li><li>of<ul><li>nested</li><li>items</li></ul></li><li>and back</li></ul><ol><li>Ordered</li><li>list</li><li>of<ol><li>nested</li><li>items</li></ol></li><li>and back</li></ol><p><a name="an-anchor"></a> This is a <code>typewriter text</code>, <em>emphasis</em>, <strong>bold</strong>. <em>Emphasis with <code>typewriter</code> and <strong>bold</strong> nested.</em> <a href="http://google.com">http:/<wbr />/<wbr />google.com</a> and <a href="http://google.com">URL</a>. <small>Small <em>text</em>.</small> En-dash &ndash; and em-dash &mdash;. Reference to a <a href="#section" class="m-doc">Page section</a>. Named reference with special characters in title: <a href="#section" class="m-doc">&raquo; Warnings &laquo;</a>. Reference with escaped characters in&nbsp;title: <a href="#an-anchor" class="m-doc">&lt;anchor&gt;</a>.</p><p>2<sup>nd</sup> is L<sub>&infin;</sub> &forall; &nabla; &pi; &real; &image; This costs no $, &euro;, &pound;, &yen; or &curren;.</p><p>Empty elements:</p><pre></pre><hr/><p>Above is a horizontal line.</p></section>
       </div>
     </div>
   </div>

diff --git a/documentation/test_doxygen/contents_unexpected_sections/File_8h.html b/documentation/test_doxygen/contents_unexpected_sections/File_8h.html
index a57d93e83ed1f856e6581a479045feeb4fea18b1..57cd0e65c1ea88472e2b67d24622e133ba258f99 100644 (file)
--- a/documentation/test_doxygen/contents_unexpected_sections/File_8h.html
+++ b/documentation/test_doxygen/contents_unexpected_sections/File_8h.html
@@ -52,7 +52,7 @@
           <h2><a href="#typedef-members">Typedefs</a></h2>
           <dl class="m-doc">
             <dt id="ab3c402cbc128c888732541f75dbd3952">
-              using <a href="#ab3c402cbc128c888732541f75dbd3952" class="m-doc-self">Bar</a> = <a href="File_8h.html#aa621f6f849ec2327dabfc4392fd59a70" class="m-doc">Foo</a>
+              using <a href="#ab3c402cbc128c888732541f75dbd3952" class="m-doc-self">Bar</a> = <a href="#aa621f6f849ec2327dabfc4392fd59a70" class="m-doc">Foo</a>
             </dt>
             <dd>A typedef.</dd>
           </dl>