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.

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

Provide sensible defaults when using --source-service argument #24

Open
franklinsch opened this issue Aug 4, 2022 · 0 comments
Open
Labels
enhancement New feature or request

Comments

@franklinsch
Copy link
Contributor

franklinsch commented Aug 4, 2022

docc added support for specifying information about the remote source repository where the project is hosted (e.g., its GitHub URL) in swiftlang/swift-docc#256, so that it can automatically emit a link to the symbol's source code.

Example invocation:

swift package generate-documentation \
  --source-service github \
  --source-service-base-url https://github.com/<org>/<repo>/blob/main \
  --checkout-path <path to local checkout>

Since SwiftPM already has smarts about the repo in which the package resides, the plugin should be able to fill in some of the arguments above by default. For example, it could pass the root path of the current repository to the --checkout-path argument. Maybe it could also find the appropriate --source-service-base-url value by inspecting the git remote's URL. I'm not sure whether these values can be grabbed using the current plugin API—it's possible there it additional information that SwiftPM would need to surface to make this work.

Importance:

This feature would make it easier to automatically include links back to documented symbols' source code on remote source services like GitHub. It's not critical though, because the values you need pass to DocC are pretty much constant and can be provided via a wrapper script.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant