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-15408] Building documentation with a fallback display name that includes a space produces a broken-looking article #211

Closed
ethan-kusters opened this issue Oct 29, 2021 · 7 comments
Assignees
Labels
bug Something isn't working

Comments

@ethan-kusters
Copy link
Contributor

Previous ID SR-15408
Radar rdar://84810134
Original Reporter @ethan-kusters
Type Bug
Status Resolved
Resolution Done

Attachment: Download

Environment

Reproduced with commit hash ba393152de75579fe4c60a8d7da2b3a719c31998 on the main branch.

Additional Detail from JIRA
Votes 0
Component/s Swift-DocC
Labels Bug, StarterBug
Assignee @d-ronnqvist
Priority Medium

md5: bd37b05faf06107586133ec6b88d0a65

Issue Description:

If I pass a fallback display name with a space (like --fallback-display-name "My Display Name") to docc, along with a valid symbol graph, DocC generates an article with ``My Display Name`` as the H1 heading and organizes it under an “Articles” topic group on my top-level framework page. I don’t expect this article to be created at all.

Reproduction Steps:

  1. Download the attached symbol graph

  2. Run the following:

docc preview --fallback-display-name "Tiny Framework" --fallback-bundle-identifier TinyFramework --fallback-bundle-version 1 --additional-symbol-graph-files /path/to/Tiny_Framework.symbols.json
@swift-ci
Copy link

swift-ci commented Nov 2, 2021

Comment by Waheed Afolabi (JIRA)

Hi @ethan-kusters, I'd like to take this up if I can get some guidance!

@d-ronnqvist
Copy link
Contributor

Hi waheedNowLovesSwift (JIRA User), if you still like to take this I can help you with that.

There's a type called GeneratedDataProvider that generates a documentation bundle when docc is passed a directory of symbol graph files without also being passed a documentation catalog as input.

This generated bundle is defined to contain a single markup file and the in-memory content for that file is generated here.

There's an assumption here that the display name provided via `--fallback-display-name` matches the module name of one of the symbol graphs.

It would be more correct to instead generate in-memory markup files from the module names in the symbol graph files.

@d-ronnqvist
Copy link
Contributor

Alternatively I can find some time to work on this later this week.

@d-ronnqvist
Copy link
Contributor

I opened a PR here #52

@swift-ci
Copy link

swift-ci commented Dec 9, 2021

Comment by Waheed Afolabi (JIRA)

@d-ronnqvist seems you've worked on this already!?

@d-ronnqvist
Copy link
Contributor

Yes. If you want to work on something else in this area Ethan opened https://bugs.swift.org/browse/SR-15572 as a follow up change to this. I can talk give you some guidance on where in the code to work on that.

Just a heads up about that, depending on the design, that change should likely have a brief pitch in the forums since it potentially adds new developer facing syntax. If you want to work on the implementation but not make the pitch I can make the pitch in the forums and leave the implementation to you (and provide guidance).

I can also provide guidance on another bug if there's something else that you want to work on. Just assign the bug to yourself and @mention me in the comments.

@swift-ci
Copy link

Comment by Waheed Afolabi (JIRA)

Okay @d-ronnqvist I'll be glad to work on this, https://bugs.swift.org/browse/SR-15572.

Your guidance will be of immense importance for me as this would be my first contribution!

@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
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

3 participants