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

[SR-15572] [Swift-DocC] Support custom display names for frameworks #199

Closed
ethan-kusters opened this issue Dec 9, 2021 · 15 comments
Closed
Assignees
Labels
enhancement Improvements or enhancements to existing functionality

Comments

@ethan-kusters
Copy link
Contributor

Previous ID SR-15572
Radar rdar://problem/86279414
Original Reporter @ethan-kusters
Type Improvement
Status Resolved
Resolution Done
Additional Detail from JIRA
Votes 0
Component/s Swift-DocC
Labels Improvement
Assignee @d-ronnqvist
Priority Medium

md5: c3fa5665e09635e8743f8f59ebc6b0c8

Issue Description:

Today Swift-DocC always renders a framework's more technical name as the title of the framework overview page. In many scenarios, developer's will likely want to customize this value when they're not limited by what characters are valid in the framework's actual name.

For example, the SwiftDocC framework, may prefer to render as "Swift DocC" or "Swift-DocC". Or maybe "ArgumentParser" would prefer to render as "Swift Argument Parser".

Swift-DocC should expose customization on the CLI and in documentation catalogs for a module's display name.

@ethan-kusters
Copy link
Contributor Author

@swift-ci create

@swift-ci
Copy link

Comment by Waheed Afolabi (JIRA)

@d-ronnqvist I have assigned it to myself!

Could you please show me the direction to follow now!

@d-ronnqvist
Copy link
Contributor

Great! I'll post a comment with more information later today or tomorrow.

@d-ronnqvist
Copy link
Contributor

A important note

Since this is a user facing change with potentially new syntax, we would want to make a small pitch in the forums for the proposed solution (not the full evolution process, just a small post so that the community can discuss the user impact). I can help you with the pitch but the discussion is not going to conclude until sometime after the new year when people are back from vacation.

If you still want to work on this, I'll outline the design that I've been thinking of and directions for how to implement it. Just note that this design hasn't been discussed in the forums, so the final design may change.

If the pitch and discussion portion feel like to much for a first contribution I've also opened SR-15634 earlier today and left a comment with some directions of how that could be implemented.

My proposed design

The user facing changes that I've imagined here is to introduce a new @DisplayName directive that would be a child of the existing @Metadata directive. Developers would add this directive to customize the title that's displayed for a given module in the documentation extension for that module. For example:

# ``ArgumentParser``

@Metadata {
{{ @DisplayName("Swift Argument Parser")}}
{{}}}

Straightforward, type-safe argument parsing for Swift.
...

This would allow for per-page customization when a symbol's name isn't the preferred display name. (A framework's top level page represents the frameworks "module" symbol.

DocumentationExtension is an example of how such a directive could be implemented and the Metadata directive would also need to updated to parse that from its child content

With that information available on the documentation extension, when a DocumentationNode is initialized with a symbol and a documentation extension it would check if the documentation extension has specified a custom display name and set its name to a Name.conceptual(title🙂 instead of the Name.symbol(declaration🙂. It may also be necessary to do the same check for a custom display name in initializeSymbolContent(documentationExtension: engine:. I believe that only the node's name needs to change to control how the page's title.

MetadataTests has existing tests specific to how the the @Metadata directive parses its content.

This test in SemaToRenderNodeTests.swift could serve as a starting point for how to test the full flow of providing a custom display name in a directive in the documentation extension, verifying that that documentation node's name is correct, rendering that node and verifying that the render node also contains the right title (the render node's metadata hold the title for the page).

@d-ronnqvist
Copy link
Contributor

Also, If you want to implement this but not do the pitch, then I can post a pitch for this sometime after the new year.

@swift-ci
Copy link

Comment by Waheed Afolabi (JIRA)

@d-ronnqvist Thanks for your time and providing this guidance.

I'd love to implement this, as well as make the pitch but I haven't done one.

I don't know how to, but I want to start doing it![]( So, I might need some guidance on it)

After the new year is cool!

@swift-ci
Copy link

Comment by Waheed Afolabi (JIRA)

While trying to see how a pitch is done, I found this:

https://forums.swift.org/t/modify-accessors/31872

I see a pattern, however I am not sure if this particular one is too complex to study for the goal at hand, or if you have a simpler one you could point me to as a reference.

@d-ronnqvist
Copy link
Contributor

Swift-DocC uses a slightly simplified pitch/proposal process compared to the broader Swift Evolution process.

Here are a few examples of previous pitches for Swift-DocC:

This is how I would describe the current format:

  • A brief description/summary of the problem.

  • Motivation (optional): An explanation of what benefit will be provided by solving the problem. This can be left out if the benefit is clear from the problem description.

  • Proposed Solution: A high level overview that describe the intended solution.

  • Detailed Design (optional): A more in-depth description of the solution. This can be left out if most of the design is already described by the high level overview above.

  • Alternatives Considered (optional): An even briefer description of any alternatives that were considered and their drawbacks compared to the proposed solution.

@d-ronnqvist
Copy link
Contributor

waheedNowLovesSwift (JIRA User) I talked to some of my colleagues about this. We discussed two alternatives—one alternative was specifying the display name in the h1 heading and using a directive to associate the file with the symbol and the other alternative was using a different link syntax in the h1 heading—but we think that the @DisplayName directive is the better solution.

Unless you really want to write the pitch, I offering to write the pitch for this but leave the implementation to you. Pitching a design for an enhancement is above and beyond what we'd expect for a first time contribution.

@d-ronnqvist
Copy link
Contributor

I will probably post a pitch for this sometime next week. After that we'll want to give the community at least a week to provide their feedback.

@d-ronnqvist
Copy link
Contributor

@d-ronnqvist
Copy link
Contributor

waheedNowLovesSwift (JIRA User) I may try and implement this later this week or early next week.

@swift-ci
Copy link

Comment by Waheed Afolabi (JIRA)

@d-ronnqvist great to know you've done the proposal...

Is there a way I could work along, I seem blacked out on how to move!

@d-ronnqvist
Copy link
Contributor

waheedNowLovesSwift (JIRA User) I've started working in this here but there are still a few pieces remaining if you want to work on that. Let me know and we'll figure our a way to collaborate on it.

The Directive turned out to be harder to implement than what I originally intended and I needed to make some swift-markdown changes here to support an initial argument without a label / name.

@d-ronnqvist
Copy link
Contributor

This PR is merged now.

@swift-ci swift-ci transferred this issue from apple/swift-issues Apr 25, 2022
@shahmishal shahmishal transferred this issue from apple/swift May 3, 2022
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improvements or enhancements to existing functionality
Projects
None yet
Development

No branches or pull requests

3 participants