Skip to content

Symbol links with custom authored titles are rendered in code voice #632

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.

Sign up for GitHub

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

Jump to bottom
Closed
2 tasks done
ethan-kusters opened this issue Apr 25, 2023 · 12 comments · Fixed by #647
Closed
2 tasks done

Symbol links with custom authored titles are rendered in code voice #632

ethan-kusters opened this issue Apr 25, 2023 · 12 comments · Fixed by #647
Assignees
@marinaaisa
Labels
bug Something isn't working

Comments

@ethan-kusters
Copy link
Contributor

ethan-kusters commented Apr 25, 2023 •
edited
Loading

Description

Symbol links with custom authored titles are rendered in code voice

If I write a doc link with a title like

Check out [this great function](doc:Sloth/eat(_:quantity:)).

the rendered output is

Check out `this great function`.

With this great function in code voice. The custom title should respect the formatting that was provided in the link title.

Checklist

  • If possible, I've reproduced the issue using the main branch of this package.
  • This issue hasn't been addressed in an existing GitHub issue.

Swift-DocC Version Information

88d0fd6676f2a2ee2d169d813420645cf6bfd52d
@ethan-kusters ethan-kusters added the bug Something isn't working label Apr 25, 2023
@ethan-kusters
Copy link
Contributor Author

CC: @Kyle-Ye maybe you're interested in taking a look at this? It looks related to the work for swiftlang/swift-docc#271.

@ethan-kusters
Copy link
Contributor Author

rdar://108515663

@Kyle-Ye
Copy link
Contributor

Kyle-Ye commented Apr 26, 2023

CC: @Kyle-Ye maybe you're interested in taking a look at this? It looks related to the work for swiftlang/swift-docc#271.

Sorry @ethan-kusters, I'm not sure what the specific question you raised is. Does it mean that we need to respect the format in the original title, but it is not?

Could you give me an expected behavior and actual behavior (Adding some code snippet or screenshot would be appreciated.)

@Kyle-Ye
Copy link
Contributor

Kyle-Ye commented Apr 26, 2023

CC: @Kyle-Ye maybe you're interested in taking a look at this? It looks related to the work for swiftlang/swift-docc#271.

Looking at the screenshot of swiftlang/swift-docc#376, I can't see what the problem is for

Check out [this great function](doc:Sloth/eat(_:quantity:)).

@ethan-kusters
Copy link
Contributor Author

Looking at the screenshot of swiftlang/swift-docc#376, I can't see what the problem is for

Check out [this great function](doc:Sloth/eat(_:quantity:)).

That screenshot demonstrates the issue I believe:

image

The "Hi" link text in "Check out Hi" is rendered with the default font while the "this great function" link text is rendered in monospace.

Monospace should only be used if the user actually specifies it, for example:

Check out [`this great function`](doc:Sloth/eat(_:quantity:)).

So expected behavior for:

Check out [this great function](doc:Sloth/eat(_:quantity:)).

would be seeing that "this great function" rendered with the default styling. Instead, I'm seeing it rendered in monospace code font.

@Kyle-Ye
Copy link
Contributor

Kyle-Ye commented Apr 26, 2023 •
edited
Loading

Got it. I'll check and try to fix it this weekend.

@Kyle-Ye
Copy link
Contributor

Kyle-Ye commented May 1, 2023 •
edited
Loading

The generated data/documentation/slothcreator.json on swift-docc side is OK.

image

image

But the corresponding reference doc://SlothCreator/documentation/SlothCreator/Sloth/eat(_:quantity:) is determined as an internal symbol by swift-docc-render.

https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/components/ContentNode/Reference.vue#L49-L51

So currently swift-docc-render will add "CodeVoice" style to it. "CodeVoice" will use "code" tag defined in "src/styles/base/_typography.scss" which set font-family to mono family.

The same is true before swiftlang/swift-docc#376.

https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/components/ContentNode/ReferenceInternalSymbol.vue#L13-L15
https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/components/ContentNode/CodeVoice.vue#L11-L13
https://github.com/apple/swift-docc-render/blob/adadcb3e5784f899720315915640a453da3f11f6/src/styles/base/_typography.scss#L200-L204

image

So what would be your expected behaviour? Should 4 and 5 both show non-code style text?

4 [doc:Sloth/eat(_:quantity:)](doc:Sloth/eat(_:quantity:))
5 [this great function](doc:Sloth/eat(_:quantity:))

image

cc @ethan-kusters

@Kyle-Ye
Copy link
Contributor

Kyle-Ye commented May 1, 2023

TL,DR:
The custom title did respect the formatting that was provided in the link title in swift-docc side(The json content).

But if it was internal symbol, swif-docc-render will add custom css effect to it. Maybe this should fall into a swift-docc-render issue. 🤔️

@ethan-kusters
Copy link
Contributor Author

I think you're right – DocC-Render should be respecting the formatting provided in the overridingTitleInlineContent value instead of forcing monospace. I'll transfer this there.

@ethan-kusters ethan-kusters transferred this issue from swiftlang/swift-docc May 1, 2023
@mportiz08
Copy link
Contributor

Sounds reasonable, although I worry a bit about there being an expectation that a link to a symbol would be in code voice by default. I think this is probably the right way to go though since it allows for that flexibility.

I didn't even realize you could provide a custom title for a DocC symbol link now 😮

@Kyle-Ye
Copy link
Contributor

Kyle-Ye commented May 5, 2023 •
edited
Loading

I didn't even realize you could provide a custom title for a DocC symbol link now 😮

This feature is tracked as a bug via swiftlang/swift-docc#271 and implemented by swiftlang/swift-docc#376 @mportiz08

@marinaaisa marinaaisa mentioned this issue May 8, 2023
Closed
3 tasks
@marinaaisa
Copy link
Member

marinaaisa commented May 8, 2023 •
edited
Loading

Hey @ethan-kusters @Kyle-Ye @mportiz08 I opened a PR for this issue: #645
Symbol links now respect the formatting provided in overridingTitleInlineContent but this means that if overridingTitleInlineContent's type is other than symbol or codeVoice it won't be using CodeVoice component at all.

Is this how it should be?

@mportiz08 mportiz08 mentioned this issue May 8, 2023
Merged
3 tasks
mportiz08 added a commit that referenced this issue May 9, 2023
@mportiz08
Respect formatting of links to symbols using custom titles (#647)
864361e 
**Example:**

```markdown
/// Default, should use code voice: ``StringBuilder``
///
/// Custom title, should use code voice: [`custom text`](doc:StringBuilder)
///
/// Custom title, should not use code voice: [custom text](doc:StringBuilder)
///
/// Custom title, should use italics and bold: [_**custom text**_](doc:StringBuilder)
```

Resolves: #632 
Resolves: rdar://108515663
mportiz08 added a commit to mportiz08/swift-docc-render that referenced this issue May 9, 2023
@mportiz08
Respect formatting of links to symbols using custom titles (swiftlang…
bce2298 
…#647)

**Example:**

```markdown
/// Default, should use code voice: ``StringBuilder``
///
/// Custom title, should use code voice: [`custom text`](doc:StringBuilder)
///
/// Custom title, should not use code voice: [custom text](doc:StringBuilder)
///
/// Custom title, should use italics and bold: [_**custom text**_](doc:StringBuilder)
```

Resolves: swiftlang#632 
Resolves: rdar://108515663
mportiz08 added a commit that referenced this issue May 11, 2023
@mportiz08
Respect formatting of links to symbols using custom titles (#647) (#651)
910fd72 
**Example:**

```markdown
/// Default, should use code voice: ``StringBuilder``
///
/// Custom title, should use code voice: [`custom text`](doc:StringBuilder)
///
/// Custom title, should not use code voice: [custom text](doc:StringBuilder)
///
/// Custom title, should use italics and bold: [_**custom text**_](doc:StringBuilder)
```

Resolves: #632 
Resolves: rdar://108515663
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@marinaaisa marinaaisa

Labels
bug Something isn't working
Projects
None yet
Milestone
No milestone
4 participants
@mportiz08 @ethan-kusters @marinaaisa @Kyle-Ye