Customizing the auto-generated “Overview” heading in Swift-DocC articles

[ethankusters]

Hi all!

I’m excited to pitch an additional directive to enhance Swift-DocC’s support for more book-like, prose content. For additional context on the related directives that have been introduced over the last couple months, I recommend reading Supporting more types of documentation with Swift-DocC.

Today, Swift-DocC requires every page to include a subheading as the first item in the primary part of the page. This is largely a holdover from how Quick Help in Swift has always worked: if an explicit subheading is omitted, the second paragraph in a documentation comment is automatically converted into an “Overview” section with an Overview subheading. This behavior doesn’t always make sense in more prose-like, article content so I’d like to introduce an option directive to opt-out of this behavior.

I think this directive will also help in migrating existing markdown content to Swift-DocC since this is one of the more surprising behaviors Swift-DocC has. Not all markdown documents are written with the assumption that they will begin with a subheading like this – the ability to disable this behavior at a global level will lower the barrier to entry for moving existing content over to Swift-DocC.

@AutomaticSubheading

@AutomaticSubheading is a new option directive for customizing the way a page’s subheading is autogenerated.

@AutomaticSubheading accepts an unnamed parameter containing one of the following:

• enabled: A subheading will be auto-generated for the page, following Swift-DocC’s current default behavior.

  Today, this means that (in the absence of some other H2 heading below the summary sentence) an “Overview” subheading will be created for most pages and a “Discussion” subheading will be created for non-container symbols, like methods. The specifics of this behavior could change in the future; using enabled is just a way to opt-in to Swift-DocC’s default and allows for setting a global setting of disabled while still enabling the feature on certain pages.

• disabled: A subheading will not be auto-generated for the page. To include a subheading, the author can explicitly write one.

@Options(scope: global) {
  @AutomaticSubheading(disabled)
}

Examples

``SlothCreator``

Catalog sloths you find in nature and create new adorable virtual sloths.

@Options {
   @AutomaticSubheading(disabled)
}

SlothCreator provides models and utilities for creating, tracking,
and caring for sloths. The framework...

...

Future Directions

In the future, we could imagine different behaviors of automatic subheading generation. This could be supported with an additional behavior parameter. For example, if we wanted to allow for tweaking automatic subheading generation to include the second paragraph of content, instead of the first paragraph:

@AutomaticSubheading(enabled, behavior: secondParagraph)

Additionally, we might want to support customization of the heading that’s used. Maybe “Summary” is a better fit than “Overview” for some collections of documentation:

@AutomaticSubheading(enabled, custom: "Summary")

The specifics of these parameters can be left to a future pitch, I’m just listing them here to show that the first parameter of enabled/disabled does not restrict the future expansion of this directive.

---

I'm looking forward to your feedback on the naming and behavior of this new directive.

- Ethan

[krilnon (Kyle Murray)]

I'm a little bit interested in an "Alternatives Considered"-style section that talks about why omitting a subheading in the source document isn't sufficient. To your example, seems like someone new to DocC would want to write this and get the output from your screenshot:

``SlothCreator``

Catalog sloths you find in nature and create new adorable virtual sloths.

SlothCreator provides models and utilities for creating, tracking,
and caring for sloths. The framework...

I totally understand the legacy of Quick Help and such, but newcomers might lack that context.

[chuckdude]

I agree with @krilnon here. While I'm totally onboard with the possibility of omitting the "Overview" heading (or changing that to something like "Introduction" or whatever), having a heading auto-insert when that's not what you want is disruptive.

[ethankusters]

I agree with this as well! Unfortunately this is the behavior we have today though and existing content likely relies on it. I think the first step on a path to "fixing" this potentially unexpected behavior is to allow developer to opt-out or opt-in to this behavior and the second step would be to pick a new default for articles.

Turning it off without first creating an option will break existing content that relies on the autogenerated heading so we need to consider a reasonable migration path for that content. I think it should addressed with a separate pitch/thread.

[ethankusters]

I started working on the implementation for this and realized that we should likely limit this directive to apply to articles only. (This will also help with the above discussion where we may, in the future, want to make the default behavior disabled for articles.)

Disabling the autogenerated "Discussion" heading for symbols actually breaks the page layout because the symbol's declaration is placed in between the page's hero and discussion section. Removing the "Discussion" heading makes the documentation a part of the declaration section which doesn't make sense.

Here's an example:

Given that, I propose we update the originally pitched name of the directive to be

@AutomaticArticleSubheading

This will allow authors to opt-out of the automatic subheading generation for articles only (while leaving symbol pages as-is) with the following:

@Options(scope: global) {
    @AutomaticArticleSubheading(disabled)
}

For now, the default behavior of DocC if the directive is not authored will be enabled, but a future pitch could suggest changing the default to be disabled. Existing catalogs that rely on the automatic behavior could then add the following:

@Options(scope: global) {
    @AutomaticArticleSubheading(enabled)
}

to re-enable the behavior.

Again, I think that change should be left to a future pitch. We'll begin by introducing the ability to modify the default and can follow-up with a change to the default itself.

[jack (Jack Lawrence)]

@ethankusters

Again, I think that change should be left to a future pitch.

+1 I don't have a preference on changing the default behavior, but agree overall it'd be great to batch up any upcoming behavior/source breaking changes into one release and figure out some mechanism to opt into all of the new stuff at once (e.g. package min swift version or something) to reduce the pain and allow us to make bigger changes—like improving tutorial syntax.

[chuckdude]

@ethankusters

@AutomaticArticleSubheading

Do we need to spell out Automatic? Why not shorten these to AutoSubhead?

[chuckdude]

In general, I like this approach, Ethan. I've always felt that the Overview/Discussion headers disrupted the flow, and being able to go right from the Declaration into a discussion of the symbol really cleans up the page. Thank you. <3