Supporting more types of documentation with Swift-DocC

[ethankusters]

Hi Jack,

Thank you for all of this great feedback! Looking forward to your future thoughts post-digestion as well.

@jack

On the directives existing at all: I think in general it would be useful to come up with some guiding principals for parameterless container directives. They definitely serve a purpose, but there are many that aren't strictly/technically necessary and so they need to provide significant value to outweigh the indentation + discovery + complexity cost.

This is a great point. In general with Supporting more dynamic content in Swift-DocC reference documentation, I'm trying to push towards directives always semantically matching 1-1 with the resulting content when used in reference docs. The location of the directive should matter and affect the way content renders in the same way the location of any other markdown syntax matters. Like you mentioned, the way directives are used in Tutorials is much more abstract and makes use of containers in a way that I don't think makes sense when intermixing directives with a document that should be majority vanilla markdown content outside of any directive.

One of the primary reasons I think we should use the @Options container is to further enforce that the directives that go in an @Options are explicitly out-of-the-ordinary and a clear departure from the norm. All other directives should be creating content on the page and, thus, outside of a container. This is the same reason that metadata directives belong in a container.

I don't foresee needing any future container directives besides @Options and @Metadata but I think they both justify themselves since their location in the text document doesn't matter in the way it should for all other directives in a regular non-tutorial .md file.

@jack

A. Instead of three directives, one Options(<scope>) directive. This is probably the most straightforward change from your current proposal and I think it improves the syntax though it doesn't fix any other problems.

I like this idea! I think this fits in better with the rest of the directive structure and allows for more flexibility moving forward.

@Options(scope: local) {
  ...
}

@Options(scope: global) {
  ...
}

With local being the default if no scope is specified.

---

@jack

B. No GlobalOptions, instead Options when written in a framework/technology root apply globally.
C. Similar to B, but Options are inherited when placed at any level in the tree. I don't know if this is possible because I think pages can have multiple parents, but it would be neat if possible.
D. Alternatively instead of using the content tree for inheritance, use the canonical url tree: all articles inherit from the tech root, symbols inherit according to the symbol graph. This might be confusing though.
E. For GlobalOptions, introduce a configuration file or extend the SPM manifest or extend the Info.plist.

I don't think I agree with B through E. The problem I see with (B) is that I think it will be quite common for folks to want style their top-level page differently from its children. For (C), I like that idea as an option (Options(scope: children)) but I think making it the default is a little fraught for the reason you mentioned: a child can have multiple parents. For (D), I agree that would be confusing since it's a departure from the usual DocC tree structure.

(E) is definitely reasonable, but personally I think that @Options(scope: global) is more intuitive and discoverable. It also allows folks to customize options globally without adding a DocC catalog. I wouldn't want DocC to become too dependent on SPM for configuring settings like this.

- Ethan