Skip to content

Add support for options directive #368

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
Merged
merged 1 commit into from
Sep 15, 2022
Merged

Add support for options directive #368

merged 1 commit into from
Sep 15, 2022

Conversation

ethan-kusters
Copy link
Contributor

@ethan-kusters ethan-kusters commented Aug 26, 2022 •
edited
Loading

Bug/issue #, if applicable: 97737541, 97739526, 97737555, 97737552

Summary

Adds support for an @Options directive with three initial options:

Dependencies

This was referenced Sep 7, 2022
Merged
Merged
franklinsch
franklinsch reviewed Sep 14, 2022
View reviewed changes
Sources/SwiftDocC/Infrastructure/DocumentationContext.swift
summary: "Duplicate \(extraOptionsDirective.scope) \(Options.directiveName.singleQuoted) directive",
explanation: """
A DocC catalog can only contain a single \(Options.directiveName.singleQuoted) \
directive with the \(extraOptionsDirective.scope.rawValue.singleQuoted) scope.
Copy link
Contributor

Choose a reason for hiding this comment

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

Since this is a warning, it would be good to describe which one of these global options will be dropped, if possible.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

They're all dropped currently but I can update the diagnostic to clarify that. Picking a single one deterministically is somewhat non-trivial and didn't seem worth it to me since it's an unsupported workflow.

Sources/SwiftDocC/Model/Rendering/TopicsSectionStyle.swift Outdated
Comment on lines 14 to 28
case list
case compactGrid
case detailedGrid
case hidden
Copy link
Contributor

Choose a reason for hiding this comment

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

Docs for these would be nice :)

Sources/SwiftDocC/Semantics/Article/Article.swift
Comment on lines +176 to +177
An article can only contain a single \(Options.directiveName.singleQuoted) \
directive with the \(scope.rawValue.singleQuoted) scope.
Copy link
Contributor

Choose a reason for hiding this comment

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

Same comment here regarding explaining which will be dropped.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The first one will be kept and all others dropped. I updated the diagnostics to only apply to those that are dropped.

Sources/SwiftDocC/Semantics/General Purpose Analyses/HasArgumentOfType.swift
problems.append(Problem(diagnostic: diagnostic, possibleSolutions: []))
}
return nil
}
guard let value = convert(argument.value) else {
let diagnostic = Diagnostic(source: source, severity: .warning, range: argument.valueRange, identifier: "org.swift.docc.HasArgument.\(diagnosticArgumentName).ConversionFailed", summary: "Can't convert \(argument.value.singleQuoted) to type \(valueTypeDiagnosticName)")
let diagnostic = Diagnostic(source: source, severity: .warning, range: argument.valueRange, identifier: "org.swift.docc.HasArgument.\(diagnosticArgumentName).ConversionFailed", summary: "Cannot convert \(argument.value.singleQuoted) to type \(valueTypeDiagnosticName.singleQuoted)")
Copy link
Contributor

Choose a reason for hiding this comment

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

🎩

Sources/SwiftDocC/Semantics/Options/AutomaticSeeAlso.swift
public private(set) var behavior: Behavior

public enum Behavior: String, CaseIterable, DirectiveArgumentValueConvertible {
case disabled
Copy link
Contributor

Choose a reason for hiding this comment

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

Docs for these would be nice

Sources/SwiftDocC/Semantics/Options/Options.swift Outdated
public private(set) var scope: Scope = .local

@ChildDirective
public private(set) var automaticSeeAlso: AutomaticSeeAlso? = nil
Copy link
Contributor

Choose a reason for hiding this comment

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

These are the names of directives, but some of these can be confusing as property types when accessed from other pieces of the codebase. For example, I'd expect this property to be a See Also section type rather than a type that describes the behavior of See Also sections. Maybe these should be private and Options could get more semantic computed properties, like automaticSeeAlsoBehavior

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good point. I've replaced these with underscored properties and property wrappers that expose the behaviors directly.

@ethan-kusters ethan-kusters marked this pull request as ready for review September 14, 2022 15:17
@ethan-kusters
Copy link
Contributor Author

@swift-ci please test

1 similar comment
@ethan-kusters
Copy link
Contributor Author

@swift-ci please test

@ethan-kusters
Copy link
Contributor Author

@swift-ci please test macOS platform

1 similar comment
@ethan-kusters
Copy link
Contributor Author

@swift-ci please test macOS platform

@ethan-kusters
Copy link
Contributor Author

@swift-ci please test

@ethan-kusters
Add support for @Options directive
ddac0d1 
- Adds a new `@Options` directive for holding other directives describing how
  content on the local page should be autogenerated and rendered.

  This directive functions like the existing `@Metadata` directive but is used
  specifically for "option directives" that effect the way content is rendered
  on the page (and not the content itself).

  Any directive that can be used in `@Options` is called an "option directive".

  The `@Options` directive accepts a `scope` parameter of either `local` or
  `global`.  A `local` scoped `@Options` affects only the current page while a
  `global` scoped one affects the entire DocC catalog.

  Example:

    @options(scope: global) {
      @AutomaticTitleHeading(disabled)
    }

    @options {
      @AutomaticSeeAlso(disabled)
      @TopicsVisualStyle(detailedGrid)
    }

  `@Options` is described on the Swift forums here:
  https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#options-1

-------------------------------------------------------------------------------

- Adds a new `@AutomaticTitleHeading` option directive for customizing the way a
  page-title’s heading (also known as an eyebrow or kicker) is automatically
  generated.

  `@AutomaticTitleHeading` accepts an unnamed parameter of either `pageKind`
  or `disabled`.

  - `pageKind`: A page-title heading will be automatically added based on the
    page’s kind. This is Swift-DocC’s current default if no automatic subheading
    generation style is specified.

  - `disabled`: A page-title heading will not be automatically created for the
    page.

  `@AutomaticTitleHeading` is described on the Swift forums here:
  https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#automatictitleheading-4

-------------------------------------------------------------------------------

- Adds a new `@AutomaticSeeAlso` option directive for customizing the way
  See Also sections are automatically generated on a given page.

  `@AutomaticSeeAlso` accepts an unnamed parameter containing one of the following:

  - `siblingPages`: The current list of auto-generated “See Also” items based
    on sibling items. This is Swift-DocC’s current default if an automatic
    see also style is not specified.

  - `disabled`: Do not automatically generate any See Also items.

`@AutomaticSeeAlso` is described on the Swift forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#automaticseealso-14

-------------------------------------------------------------------------------

- Adds a new `@TopicsVisualStyle` option directive for customizing the way
  Topics sections are rendered on a given page.

  `@TopicsVisualStyle` accepts an unnamed parameter containing one of the
  following:

  - `list`: The current list of topics we render on page, including their
    abstracts. This is Swift-DocC’s current default if a topics style is
    not specified.

  - `compactGrid`: A grid of items based on the card image for each page.
    Includes each page’s title and card image but excludes their abstracts.

  - `detailedGrid`: A grid of items based on the card image for each page,
    includes the abstract for each page.

  - `hidden`: Don’t show child pages anywhere on the page.

`@TopicsVisualStyle` is described on the Swift forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#topicsvisualstyle-18

-------------------------------------------------------------------------------

Resolves rdar://97737541
@ethan-kusters
Copy link
Contributor Author

@swift-ci please test

@ethan-kusters ethan-kusters merged commit 3099317 into swiftlang:main Sep 15, 2022
@ethan-kusters ethan-kusters deleted the add-options branch September 15, 2022 10:37
@dobromir-hristov dobromir-hristov mentioned this pull request Sep 21, 2022
Merged
3 tasks
@amartini51 amartini51 mentioned this pull request Sep 28, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@franklinsch franklinsch franklinsch approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

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