Fix bad anchors #132

EmilyBourne · 2025-03-27T13:39:25Z

Fix bad anchors created for:

operator() (missing from OVERLOAD_OPERATORS)
Any operators containing - as this character is preserved in the anchor
Sections with template syntax in the name (e.g. MyClass<Specialisation, Specialization>)
Sections with long names truncated to end with ...
Any operator which is also overridden in a private zone (where the documentation is not extracted by doxygen)

This fixes #131

Summary by Sourcery

Improve anchor generation for documentation to handle complex operator and section naming scenarios

Bug Fixes:

Fix anchor generation for operators with special characters, including operators with hyphens and template syntax
Correct anchor generation for overloaded operators, especially those with complex names
Ensure operators are correctly identified and anchored, including previously missing operator()

Enhancements:

Enhance URL-safe name generation by stripping more special characters
Improve operator matching logic to prevent incorrect anchor generation

Chores:

Add operator() to the list of recognized overload operators

sourcery-ai · 2025-03-27T13:39:30Z

Reviewer's Guide by Sourcery

This pull request fixes several issues related to anchor generation in mkdoxy, specifically addressing problems with overloaded operators, special characters in names, and the escaping of special characters in markdown. The changes ensure that anchors are correctly generated for a wider range of cases, improving navigation and linking within the generated documentation.

Updated class diagram for Node class

classDiagram
  class Node {
    - _name: str
    - _refid: str
    - _visibility: Visibility
    + operator_num: int
    + name_url_safe: str
    + anchor: str
    + operators_total() int
  }
  note for Node.name_url_safe "Strips special characters (=~.,<>) from name"
  note for Node.anchor "Generates correct anchor name for overloaded operators and other cases"

File-Level Changes

Change	Details	Files
Correctly generate anchors for overloaded operators, including those with hyphens and those overridden in private zones.	Added logic to handle operators containing hyphens in their names when generating anchors. Ensured that private operators are not included when calculating the operator number. Modified the anchor generation logic to correctly handle the `operator()` overload.	`mkdoxy/node.py` `mkdoxy/constants.py`
Improved the generation of URL-safe names by stripping special characters and handling whitespace.	Removed special characters (=~.,<>) from the generated URL-safe names. Stripped leading/trailing whitespace and replaced internal spaces with hyphens. Refactored the name_url_safe property for better readability and maintainability.	`mkdoxy/node.py`
Escaped the '	' character in markdown to prevent rendering issues.	Added an escape for the '

Assessment against linked issues

Issue	Objective	Addressed
#131	Fix broken links for `operator()`.	✅
#131	Fix broken links for operators containing `-`.	✅
#131	Fix broken links for templated variables.	✅

Possibly linked issues

Bad links in generated files #131: The PR fixes the issue by correcting the anchor generation for operators, templated names, and long names. Fixes Bad links in generated files #131

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!
Generate a plan of action for an issue: Comment @sourcery-ai plan on
an issue to generate a plan of action for it.

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

sourcery-ai

Hey @EmilyBourne - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider consolidating the replace calls in name_url_safe into a single regex replace for better readability.

Here's what I looked at during the review

🟢 General issues: all looks good
🟢 Security: all looks good
🟢 Testing: all looks good
🟢 Complexity: all looks good
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

EmilyBourne · 2025-03-27T14:17:15Z

@sourcery-ai review

sourcery-ai

Hey @EmilyBourne - I've reviewed your changes - here's some feedback:

Overall Comments:

Consider adding a unit test to verify the generated anchors for template syntax.
The logic for handling overloaded operators seems complex; can it be simplified?

Here's what I looked at during the review

🟡 General issues: 1 issue found
🟢 Security: all looks good
🟢 Testing: all looks good
🟢 Complexity: all looks good
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

mkdoxy/node.py

EmilyBourne · 2025-03-27T15:54:14Z

@sourcery-ai review

sourcery-ai

Hey @EmilyBourne - I've reviewed your changes - here's some feedback:

Overall Comments:

It might be worth adding a unit test to verify the anchor generation logic, especially for edge cases.
Consider adding a comment explaining the regex in name_url_safe.

Here's what I looked at during the review

🟢 General issues: all looks good
🟢 Security: all looks good
🟢 Testing: all looks good
🟢 Complexity: all looks good
🟢 Documentation: all looks good

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

EmilyBourne · 2025-03-27T15:57:53Z

This PR should be ok now. Is there anywhere to add tests? If not then I can at least confirm that it runs correctly on the repo that I am working with (see gyselax/gyselalibxx#193 ) and removes all the warnings that I was seeing, without creating any new warnings.

JakubAndrysek · 2025-05-22T20:18:38Z

Can you please create a PR for #126 or after merging it?

More info there: #135 (comment)

Thanks

EmilyBourne added 2 commits March 27, 2025 13:03

Missing OVERLOAD_OPERATOR

d3bca7b

Strip more special characters. Convert spaces after stripping

35e3b22

sourcery-ai bot reviewed Mar 27, 2025

View reviewed changes

EmilyBourne added 3 commits March 27, 2025 14:40

Escape backslash

61c9133

Use a regex as suggested by sourcery

65b52a0

Correct anchor for operators with -

37b67f1

sourcery-ai bot reviewed Mar 27, 2025

View reviewed changes

mkdoxy/node.py Outdated Show resolved Hide resolved

EmilyBourne added 2 commits March 27, 2025 15:21

Add suggested doc

3e9da38

Exclude private children

6adef20

sourcery-ai bot reviewed Mar 27, 2025

View reviewed changes

JakubAndrysek mentioned this pull request May 22, 2025

Proposal: Auto-link to API docs #135

Open

Formatting

a72dbcc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Fix bad anchors #132

Fix bad anchors #132

Uh oh!

EmilyBourne commented Mar 27, 2025 •

edited by sourcery-ai bot

Loading

Uh oh!

sourcery-ai bot commented Mar 27, 2025 •

edited

Loading

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

sourcery-ai bot left a comment

Uh oh!

EmilyBourne commented Mar 27, 2025

Uh oh!

sourcery-ai bot left a comment

Uh oh!

Uh oh!

EmilyBourne commented Mar 27, 2025

Uh oh!

sourcery-ai bot left a comment

Uh oh!

EmilyBourne commented Mar 27, 2025

Uh oh!

JakubAndrysek commented May 22, 2025

Uh oh!

Uh oh!

Uh oh!

Fix bad anchors #132

Are you sure you want to change the base?

Fix bad anchors #132

Uh oh!

Conversation

EmilyBourne commented Mar 27, 2025 • edited by sourcery-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by Sourcery

Uh oh!

sourcery-ai bot commented Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide by Sourcery

Updated class diagram for Node class

File-Level Changes

Assessment against linked issues

Possibly linked issues

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

EmilyBourne commented Mar 27, 2025

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

EmilyBourne commented Mar 27, 2025

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

EmilyBourne commented Mar 27, 2025

Uh oh!

JakubAndrysek commented May 22, 2025

Uh oh!

Uh oh!

EmilyBourne commented Mar 27, 2025 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Mar 27, 2025 •

edited

Loading