From db06ed9d7c5a65c688be36edd5e03b550143368d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 14 Sep 2024 02:07:55 +0200 Subject: [PATCH] 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. --- documentation/doxygen.py | 10 +++++++++- .../compound_listing/Directory/Sub/Class.h | 3 +++ .../classRoot_1_1Directory_1_1Sub_1_1Class.html | 2 +- .../group__fizzbuzz.html | 2 +- .../test_doxygen/contents_sections_headings/index.html | 2 +- .../test_doxygen/contents_typography/index.html | 2 +- .../contents_unexpected_sections/File_8h.html | 2 +- 7 files changed, 17 insertions(+), 6 deletions(-) diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 0e688489..24182931 100755 --- 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 + # 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 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 2e0f4486..f426f538 100644 --- 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 28afc01b..7fb8fac6 100644 --- 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 @@ -

A section

Text.

Subsection

Subsection 2

Subsection 3

Section 2

+

A section

Text.

Subsection

Subsection 2

Subsection 3

Section 2

Link to this page shouldn't contain the filename while link to another page should. Same with section references vs external pages.

Public types

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 8410f8f7..e9d8ad8e 100644 --- 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 @@ void bar()

Bar.

-

More details

+

More details

diff --git a/documentation/test_doxygen/contents_sections_headings/index.html b/documentation/test_doxygen/contents_sections_headings/index.html index d1dbabb7..9165816a 100644 --- a/documentation/test_doxygen/contents_sections_headings/index.html +++ b/documentation/test_doxygen/contents_sections_headings/index.html @@ -22,7 +22,7 @@

My Project

-

Page section

Text.

Page subsection

Text!

Sub-sub section

Reference to a page subsection and Sub-sub section.

+

Page section

Text.

Page subsection

Text!

Sub-sub section

Reference to a page subsection and Sub-sub section.

diff --git a/documentation/test_doxygen/contents_typography/index.html b/documentation/test_doxygen/contents_typography/index.html index f1dccd1f..2e49739a 100644 --- a/documentation/test_doxygen/contents_typography/index.html +++ b/documentation/test_doxygen/contents_typography/index.html @@ -25,7 +25,7 @@

A blockquote.

Paragraph
with
explicit
line
breaks.

Preformatted text.

Page section

Differently
   preformatted
-text.
  1. Ordered
  2. list
  3. of
    1. nested
    2. items
  4. and back

This is a typewriter text, emphasis, bold. Emphasis with typewriter and bold nested. http://google.com and URL. Small text. En-dash – and em-dash —. Reference to a Page section. Named reference with special characters in title: » Warnings «. Reference with escaped characters in title: <anchor>.

2nd is L∞ ∀ ∇ π ℜ ℑ This costs no $, €, £, ¥ or ¤.

Empty elements:

Above is a horizontal line.

+text.
  1. Ordered
  2. list
  3. of
    1. nested
    2. items
  4. and back
 This is a typewriter text, emphasis, bold. Emphasis with typewriter and bold nested. http://google.com and URL. Small text. En-dash – and em-dash —. Reference to a Page section. Named reference with special characters in title: » Warnings «. Reference with escaped characters in title: <anchor>.
2nd is L∞ ∀ ∇ π ℜ ℑ This costs no $, €, £, ¥ or ¤.
Empty elements:
Above is a horizontal line.

       
     
   
diff --git a/documentation/test_doxygen/contents_unexpected_sections/File_8h.html b/documentation/test_doxygen/contents_unexpected_sections/File_8h.html
index a57d93e8..57cd0e65 100644
--- a/documentation/test_doxygen/contents_unexpected_sections/File_8h.html
+++ b/documentation/test_doxygen/contents_unexpected_sections/File_8h.html
@@ -52,7 +52,7 @@
           
Typedefs

           

             

-              using Bar = Foo
+              using Bar = Foo
             

             
A typedef.

           

-- 
2.30.2