Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add escape_square_brackets into comment_formats markdown configuration #379

Merged
merged 3 commits into from
Sep 19, 2024

Conversation

lquerel
Copy link
Contributor

@lquerel lquerel commented Sep 19, 2024

The cargo doc command does not properly handle non-escaped text containing square brackets when these brackets are not intended to represent links (e.g., This is a [text] with square brackets that doesn't represent a link). This PR addresses the issue by introducing a new flag escape_square_brackets in the markdown configuration of the comment_formats section.

This new flag ensures that text with square brackets, which are not intended as links, is properly escaped in the generated documentation.

Example:

Input Text:

In some cases, a [URL] may refer to an [IP](http://ip.com) and/or port directly.
The file \[extension\] is extracted \[from] the `url.full`, excluding the leading dot.

Output Without the Flag:

Without the new flag, the following text is returned by the comment filter:

In some cases, a [URL] may refer to an [IP](http://ip.com) and/or port directly.
The file \[extension\] is extracted \[from] the `url.full`, excluding the leading dot.

Output With the Flag Enabled:

When the new flag is enabled, the output becomes:

In some cases, a \[URL\] may refer to an [IP](http://ip.com) and/or port directly.
The file \[extension\] is extracted \[from\] the `url.full`, excluding the leading dot.

Closes #374

@lquerel lquerel requested a review from a team as a code owner September 19, 2024 01:38
@lquerel lquerel self-assigned this Sep 19, 2024
@lquerel lquerel added documentation Improvements or additions to documentation enhancement New feature or request and removed documentation Improvements or additions to documentation labels Sep 19, 2024
@@ -579,6 +579,7 @@ comment_formats: # optional

# Fields specific to 'markdown' format
escape_backslashes: <bool> # Whether to escape backslashes in markdown (default: false).
escape_square_brackets: <bool> # Whether to escape square brackets in markdown (default: false).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we have brackets already in the conventions, what is happening there today? And then, shouldn't this be true by default, as we want to keep the brackets to match the source data? 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree. It’s probably better to have this escaping enabled by default. I will make this change before merging. Thanks

@lquerel lquerel merged commit 2d4d070 into open-telemetry:main Sep 19, 2024
21 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

Add a flag in comment_formats to escape invalid markdown links
3 participants