Update contributor documentation to reflect changes in input discovery #1060
Conversation
d-ronnqvist
force-pushed
the
input-discovery-contributor-docs
branch
3 times, most recently
from
7aea786 to
22962bf
Compare
|
|
||
| When a documentation bundle is found in the workspace by a ``DocumentationWorkspaceDataProvider``, the following files are recognized and processed (others are ignored): | ||
| - Markup files, tutorial files, and assets (for example images) | ||
| - Symbol graph files, describing the symbols in a given module (types, functions, variables, etc.) and their relationships (inheritance, conformance, etc.) |
There was a problem hiding this comment.
I think describing the extensions for each of these file types is useful. Can we add that back here?
There was a problem hiding this comment.
I didn't feel like the top-level page about the compiler pipeline was the right place to enumerate all the support file extensions in a catalog.
I'll see if I can find a better place for this information.
There was a problem hiding this comment.
I noticed that the top-level page also listed the possible content of a catalog so I updated that to mention the file extensions .
| And finally to print all known paths in the context: | ||
|
|
||
| ```swift | ||
| context.knownIdentifiers.forEach({ print($0) }) |
There was a problem hiding this comment.
Is this no longer true/possible?
There was a problem hiding this comment.
It's still both true and possible. I just felt that it wasn't relevant.
| guard let catalogURL = try inputProvider.findCatalog(startingPoint: startingPoint) else { | ||
| return | ||
| } | ||
| let bundle = try inputProvider.makeInputs(contentOf: catalogURL, options: BundleDiscoveryOptions()) |
There was a problem hiding this comment.
What do you think about briefly explaining BundleDiscoveryOptions? For example, that BundleDiscoveryOptions can also include Info.plist values?
There was a problem hiding this comment.
Hm... I think for the purposes of this article it's sufficient to see BundleDiscoveryOptions being used and showing that additional symbol graph locations are passed in the options.
If the developer goes to try and discover inputs themselves they would either try to create a new value and discover the first argument for both initializers is some form of Info.plist values, or they would look for an options value that's already passed to their scope and use that.
There was a problem hiding this comment.
Somewhat related, with the new input discovery structure I find it a bit weird that the catalog is separate from the options. If BundleDiscoveryOptions didn't already exist I don't know if I would group the Info.plist fallbacks and the symbol graph URLs without also grouping the catalog URL.
It's also weird that it's named "options" but the information it holds is more user-provided inputs. allowArbitraryCatalogDirectories would make sense as an option but that is its own parameter.
At least now there's only really two places that use it (DocumentationContext/InputsProvider and DocumentationBundle/Info/init(from:bundleDiscoveryOptions:derivedDisplayName:) neither of which are public) so it would be easy to change in the future if we have new ideas about how to group this information.
There was a problem hiding this comment.
Makes sense. I agree -- from the name, it wasn't immediately clear (to me) what BundleDiscoveryOptions is. But you're right that it would hopefully become clearer when the developer goes to discover inputs.
Co-authored-by: Maya Epps <[email protected]>
d-ronnqvist
force-pushed
the
input-discovery-contributor-docs
branch
from
b22d790 to
b6a2079
Compare
|
@swift-ci please test |
Bug/issue #, if applicable: rdar://136208312
Summary
This updates the contributor documentation to reflect the changes in documentation input discovery and context creation from #1059, #1057, #1049, #1038, and #1031
It also makes some clarifications about what the documentation inputs are and how the user can provide them, the role of a documentation context, and the files that a documentation catalog can contain.
Dependencies
This builds on the changes from #1059 (Deprecate two-step documentation context creation) which build on the changes from #1057 (Pass documentation context its only bundle during initialization)
This diff shows the changes that are specific to this PR.
Testing
Preview the contributor documentation in
SwiftDocCChecklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
[ ] Added tests./bin/testscript and it succeeded