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.

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

Add authoring support for @TitleHeading directive #611

Merged
merged 18 commits into from
Jun 12, 2023
Merged

Add authoring support for @TitleHeading directive #611

merged 18 commits into from
Jun 12, 2023

Conversation

emilyychenn
Copy link
Contributor

@emilyychenn emilyychenn commented Jun 6, 2023 •
edited
Loading

Bug/issue #: #408

Summary

Add support for an @TitleHeading directive that allows for customizing the text of a page-title heading (also known as an eyebrow or kick).

Testing

With a documentation catalog

In a documentation catalog with symbol graph files and documentation extension files:

  1. Preview the documentation for that docc catalog with docc preview /path/to/Example.docc
  2. In the documentation extension file for the module symbol: add a title heading directive. For example: 
    @Metadata {
    @TitleHeading("Release Notes")
}
  3. Navigate to that page in the preview. The custom title heading ("Release Notes") should appear as the title heading for that symbol.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

  • Added tests
  • Ran the ./bin/test script and it succeeded
  • Updated documentation if necessary

@emilyychenn emilyychenn marked this pull request as ready for review June 9, 2023 18:46
@emilyychenn emilyychenn requested a review from ethan-kusters June 9, 2023 18:46
ethan-kusters
ethan-kusters reviewed Jun 9, 2023
View reviewed changes
Copy link
Contributor

@ethan-kusters ethan-kusters left a comment

Choose a reason for hiding this comment

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

Looks great! Thank you for opening this. I just left a few comments about formatting and suggestions for improving test coverage.

Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift Outdated Show resolved Hide resolved
Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift Outdated Show resolved Hide resolved
Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md Outdated Show resolved Hide resolved
Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift Show resolved Hide resolved
Tests/SwiftDocCTests/Semantics/MetadataTests.swift Outdated Show resolved Hide resolved
Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift Show resolved Hide resolved
Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift Outdated Show resolved Hide resolved
Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift Outdated Show resolved Hide resolved
@ethan-kusters
Copy link
Contributor

@swift-ci please test

@emilyychenn emilyychenn requested a review from ethan-kusters June 9, 2023 21:26
ethan-kusters
ethan-kusters reviewed Jun 9, 2023
View reviewed changes
Copy link
Contributor

@ethan-kusters ethan-kusters left a comment

Choose a reason for hiding this comment

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

Documentation is looking really great – thank you!

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Outdated Show resolved Hide resolved
Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Outdated Show resolved Hide resolved
Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Outdated Show resolved Hide resolved
Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift Show resolved Hide resolved
Tests/SwiftDocCTests/Semantics/MetadataTests.swift Outdated Show resolved Hide resolved
Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift Show resolved Hide resolved
emilyychenn and others added 4 commits June 9, 2023 15:31
@emilyychenn emilyychenn requested a review from ethan-kusters June 9, 2023 22:40
ethan-kusters
ethan-kusters reviewed Jun 9, 2023
View reviewed changes
Copy link
Contributor

@ethan-kusters ethan-kusters left a comment

Choose a reason for hiding this comment

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

Looks great! Just had a couple final documentation thoughts.

Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift Outdated Show resolved Hide resolved
Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Outdated Show resolved Hide resolved
Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Outdated Show resolved Hide resolved
Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift Show resolved Hide resolved
@ethan-kusters
Copy link
Contributor

@swift-ci please test

@emilyychenn emilyychenn self-assigned this Jun 12, 2023
ethan-kusters
ethan-kusters approved these changes Jun 12, 2023
View reviewed changes
Copy link
Contributor

@ethan-kusters ethan-kusters left a comment

Choose a reason for hiding this comment

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

Looks great! Thank you! Excited to have this in.

@ethan-kusters
Copy link
Contributor

@swift-ci please test

@emilyychenn emilyychenn merged commit f3a1f62 into swiftlang:main Jun 12, 2023
@emilyychenn emilyychenn deleted the add-title-heading branch June 12, 2023 21:34
emilyychenn added a commit to emilyychenn/swift-docc that referenced this pull request Jun 12, 2023
@emilyychenn
Add authoring support for @TitleHeading directive (swiftlang#611)
400d96e 
A new `@TitleHeading` metadata directive for customizing the text of a page-title heading (also known as an eyebrow or kick).

`@TitleHeading` accepts an unnamed parameter containing containing the page-title’s heading text.

    @metadata {
      @TitleHeading("Release Notes")
    }

This feature has been pitched on the forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#titleheading-10

rdar://110662981
@emilyychenn emilyychenn mentioned this pull request Jun 12, 2023
Merged
emilyychenn added a commit that referenced this pull request Jun 13, 2023
@emilyychenn
Add authoring support for @TitleHeading directive (#611) (#623)
6f72447 
A new `@TitleHeading` metadata directive for customizing the text of a page-title heading (also known as an eyebrow or kick).

`@TitleHeading` accepts an unnamed parameter containing containing the page-title’s heading text.

    @metadata {
      @TitleHeading("Release Notes")
    }

This feature has been pitched on the forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#titleheading-10

rdar://110662981
@DavidBrunow DavidBrunow mentioned this pull request Jun 2, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ethan-kusters ethan-kusters ethan-kusters approved these changes

Assignees

@emilyychenn emilyychenn

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@emilyychenn @ethan-kusters