Swift Package Manager command plugin for Swift-DocC

Overview

Swift-DocC Plugin

The Swift-DocC plugin is a Swift Package Manager command plugin that supports building documentation for SwiftPM libraries and executables.

Usage

Please see the plugin's documentation for more detailed usage instructions.

Adding the Swift-DocC Plugin as a Dependency

To use the Swift-DocC plugin with your package, first add it as a dependency:

let package = Package(
    // name, platforms, products, etc.
    dependencies: [
        // other dependencies
        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
    ],
    targets: [
        // targets
    ]
)

Swift 5.6 is required in order to run the plugin.

Converting Documentation

You can then invoke the plugin from the root of your repository like so:

swift package generate-documentation

This will generate documentation for all compatible targets defined in your package and its dependencies and print the location of the resulting DocC archives.

If you'd like to generate documentation for a specific target and output that to a specific directory, you can do something like the following:

swift package --allow-writing-to-directory ./docs \
    generate-documentation --target MyFramework --output-path ./docs

Notice that the output path must also be passed to SwiftPM via the --allow-writing-to-directory option. Otherwise SwiftPM will throw an error as it's a sandbox violation for a plugin to write to a package directory without explicit permission.

Any flag passed after the generate-documentation plugin invocation is passed along to the docc command-line tool. For example, to take advantage of Swift-DocC's new support for hosting in static environments like GitHub Pages, you could run the following:

swift package --allow-writing-to-directory ./docs \
    generate-documentation --target MyFramework --output-path ./docs \
    --transform-for-static-hosting --hosting-base-path MyFramework

Previewing Documentation

The Swift-DocC plugin also supports previewing documentation with a local web server. However, unlike converting documentation, previewing is limited to a single target a time.

To preview documentation for the MyFramework target, you could run the following:

swift package --disable-sandbox preview-documentation --target MyFramework

To preview documentation for a product defined by one of your package's dependencies, you could run the following:

swift package --disable-sandbox preview-documentation --product OtherFramework

Hosting Documentation

For details on how to best build documentation for hosting online and a specific tutorial for publishing to GitHub Pages, please see the plugin's documentation.

Submitting a Feature Request

For feature requests, please feel free to create an issue on Swift JIRA with the New Feature type or start a discussion on the Swift Forums.

Don't hesitate to submit a feature request if you see a way the Swift-DocC plugin can be improved to better meet your needs.

All user-facing features must be discussed in the Swift Forums before being enabled by default.

Contributing to the Swift-DocC Plugin

Please see the contributing guide for more information.

Comments
  • Adopt new SwiftPM plugin Argument Parsing API

    Adopt new SwiftPM plugin Argument Parsing API

    Summary

    Updates the SwiftPM plugin to use the latest Argument Parsing API that will ship with Swift 5.6.

    This also includes some general improvements to help output (--help) in preparation for the 1.0 release of the plugin.

    Details

    The SwiftPM plugin API has been updated so that options like --target and --product are passed directly to the plugin instead of to the package manager.

    This means that instead of calling the plugin with something like:

    swift package --target SwiftMarkdown generate-documentation
    

    you would now do:

    swift package generate-documentation --target SwiftMarkdown
    

    This allows us to be a little smarter about choosing which products to build. For example, now when a user invokes the basic

    swift package generate-documentation
    

    we will also generate documentation for dependencies. Similarly, this allows clients to specify products of dependencies which makes doing something like

    swift package preview-documetnation --product ArgumentParser
    

    possible for packages that import ArgumentParser.

    Dependencies

    This change depends on the latest Swift 5.6 nightly toolchain that includes the new ArgumentParsing API.

    Testing

    Add the version of the plugin on this branch as a dependency of a package with:

    .package(url: ["https://github.com/apple/swift-docc-plugin](https://github.com/ethan-kusters/swift-docc-plugin.git)", branch: "adopt-new-argument-parsing-api")
    

    Checklist

    Make sure you check off the following items. If they cannot be completed, provide a reason.

    • [x] Added tests
    • [x] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by ethan-kusters 16
  • SE-0356: Snippet slice parsing

    SE-0356: Snippet slice parsing

    Rewrite the snippet parser to support slicing.

    See: https://github.com/apple/swift-evolution/blob/main/proposals/0356-swift-snippets.md#slices

    Adopt SymbolKit model changes related to slicing.

    Remove experimental guard flag for snippet functionality.

    rdar://95220356

    opened by bitjammer 12
  • Update Documentation For Private Github Pages

    Update Documentation For Private Github Pages

    Bug/issue #, if applicable: https://forums.swift.org/t/docc-for-private-github-repos/55770/2

    Summary

    Added documentation for github private pages . For private repos, hosting-base-path is not needed, as each repo is served from its own subdomain. Also the url format for such pages is also different.

    Dependencies

    Not Applicable

    Testing

    Not Applicable

    Checklist

    • [ ] Added tests
    • [ ] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by denil-ct 9
  • Snippets

    Snippets

    Summary

    Add snippets support to the Swift DocC Plugin.

    Dependencies

    No outstanding PR dependencies, although this does add a new dependency on SymbolKit, which should match DocC's version.

    Testing

    New unit and integration tests added. Run tests as usual.

    Checklist

    Make sure you check off the following items. If they cannot be completed, provide a reason.

    • [x] Added tests
    • [x] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by bitjammer 7
  • [`./bin/test`] Allow skipping clone of `swift-docc` and `swift-docc-render-artifact`

    [`./bin/test`] Allow skipping clone of `swift-docc` and `swift-docc-render-artifact`

    From https://github.com/apple/swift-docc-plugin/pull/21#discussion_r929419898

    In some scenarios, running swift-docc-plugin tests against the built-in docc in the installed toolchain could save time. Add an option to ./bin/test to skip cloning swift-docc and swift-docc-render-artifact and setting the environment variables to use those.

    Behavior:

    If --skip-building-upstream-docc (or perhaps an environment variable) is set:

    • Don't set the following:
      • SWIFT_DOCC_ROOT
      • SWIFT_DOCC_RENDER_ARTIFACT_ROOT
      • SWIFT_DOCC_BRANCH
      • SWIFT_DOCC_RENDER_ARTIFACT_BRANCH
    • Don't clone swift-docc or swift-docc-render-artifact
    • Also don't set:
      • DOCC_EXEC
      • DOCC_HTML_DIR

    See the above mentioned pull request for new code that should be skipped in this case.

    enhancement good first issue improvement 
    opened by bitjammer 6
  • Preview: remove use of `signal` on Windows

    Preview: remove use of `signal` on Windows

    Windows does not support signal(2). Instead, use TerminateProcess to terminate the process. We will not properly handle the termination of child processes for the preview process, which should be handled by the construction of a job object that all child processes are attached to such that when the parent process is terminated, the children will be properly reaped. This is required to enable building the plugin on Windows which is a dependency for swift-syntax.

    opened by compnerd 4
  • Allow test script to use upstream DocC.

    Allow test script to use upstream DocC.

    Expect SWIFT_DOCC_BRANCH and SWIFT_DOCC_RENDER_ARTIFACT_BRANCH in the environment. If both are set when running ./bin/test, clone the respective repos at those branches and set DOCC_EXEC and DOCC_HTML_DIR when running the tests.

    Exclude these cloned directories from ./bin/check-source.

    rdar://97294776

    opened by bitjammer 3
  • Update for Github Issues Migration

    Update for Github Issues Migration

    Summary

    • Added issue templates for feature request and bug report. (based on swift-docc)
    • Updated feature requests and bug report sections of readme with the new templates.

    Checklist

    Make sure you check off the following items. If they cannot be completed, provide a reason.

    • [ ] Added tests
    • [ ] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by denil-ct 3
  • Set a custom display name for the plugin's documentation

    Set a custom display name for the plugin's documentation

    Summary

    With Swift 5.7, Swift-DocC has support for setting a custom display name in documentation. We can use it here to render the top-level page of the plugin's documentation as "Swift-DocC Plugin" instead of "SwiftDocCPlugin".

    Screen Shot 2022-06-17 at 2 19 03 PM

    Checklist

    Make sure you check off the following items. If they cannot be completed, provide a reason.

    • [ ] ~~Added tests~~ NFC
    • [x] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by ethan-kusters 2
  • Add package plugin instructions to documentation

    Add package plugin instructions to documentation

    Bug/issue #, if applicable: N/A

    Summary

    Add instructions to set up the plugin in the documentation. When reading the documentation at https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/, it might not be totally clear that the plugin needs to be added to your package first, especially if the developer is not yet familiar with the concept of SwiftPM plugins.

    Dependencies

    None.

    Testing

    No functional changes.

    Checklist

    • ~[ ] Added tests~ N/A
    • [x] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by franklinsch 2
  • Fix compatibility with Xcode 13.3 Beta 3

    Fix compatibility with Xcode 13.3 Beta 3

    Summary

    The PackagePlugin module in Xcode 13.3 Beta 3 requires the async version of the CommandPlugin.performCommand method.

    This marks the performCommand method in both SwiftDocCConvert and SwiftDocCPreview as async to meet this requirement.

    Testing

    Build the version of the plugin in this PR with Xcode 13.3 Beta 3 and confirm that the build passes.

    Checklist

    Make sure you check off the following items. If they cannot be completed, provide a reason.

    • [ ] ~~Added tests~~ Non-functional change.
    • [x] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by ethan-kusters 2
  • Unwrap variables in a way Xcode 13 can be compiled

    Unwrap variables in a way Xcode 13 can be compiled

    Bug/issue: #30

    Summary

    Allows Documentation to be generated against Xcode 13

    Dependencies

    N/A

    Testing

    No new tests added, all current tests run and pass, no new functionality added

    Checklist

    Make sure you check off the following items. If they cannot be completed, provide a reason.

    • [x] Added tests
    • [x] Ran the ./bin/test script and it succeeded
    • [x] Updated documentation if necessary
    opened by SRowley90 0
  • Running the plugin using Xcode 13 produces error 'variable binding in a condition requires an initializer'

    Running the plugin using Xcode 13 produces error 'variable binding in a condition requires an initializer'

    When trying to generate Documentation Using Xcode 13 from the main branch, 2 errors occur with the same message variable binding in a condition requires an initializer both in the Snippet Parser class of the Package. This does not occur when using the package with Xcode 14 (beta at the time of writing this)

    Checklist

    • [x] If possible, I've reproduced the issue using the main branch of this package.
    • [x] This issue hasn't been addressed in an existing GitHub issue.

    Expected behavior

    Documentation to be generated when using Xcode 13

    Actual behavior

    Error (variable binding in a condition requires an initializer) is thrown.

    Screenshot 2022-09-21 at 14 43 43

    Steps to Reproduce

    Using the following command against the main branch of this repository causes the issue, it does not happen when using Xcode 14 or when pointing to the older 1.0.0 Release (but obviously this is old).

    swift package --allow-writing-to-directory ./public generate-documentation --target JLRAnalytics --disable-indexing --output-path ./public --transform-for-static-hosting --hosting-base-path 'jlranalytics'

    Swift-DocC Plugin Version Information

    Swift-DocC plugin version: main Swift Compiler version: swift-driver version: 1.45.2 Apple Swift version 5.6.1 (swiftlang-5.6.0.323.66 clang-1316.0.20.12) Target: x86_64-apple-macosx12.0

    bug 
    opened by SRowley90 0
  • Docc cannot generate the documentation folder

    Docc cannot generate the documentation folder

    Docc plugin is not able to generate the documentation folder for the target.

    Checklist

    I'm using the main branch before I was using 1.0.0

    Expected behavior

    Generate documentation folder.

    Actual behavior

    It finds my docc file but when I go to the archive folder there is no documentation which is the reason why I can't see the documentation correctly. I tested it with a custom symbol graph and it works but I'm not sure this plugin support graph. But It generates some simple package that I write!

    Steps to Reproduce

    swift package --allow-writing-to-directory ./docs
    generate-documentation
    --target TARGET
    --output-path ./docs
    --transform-for-static-hosting
    --hosting-base-path TARGET
    --disable-indexing

    Swift-DocC Plugin Version Information

    Swift-DocC plugin version: 1.0.0 and main commit hash. 3303b164430d9a7055ba484c8ead67a52f7b74f6 , 6a6577adb48651a1ca7dee6861c894ee6ca66021

    Swift Compiler version: Output from swiftc --version. swift-driver version: 1.62.8 Apple Swift version 5.7 (swiftlang-5.7.0.127.4 clang-1400.0.29.50) Target: x86_64-apple-macosx12.0

    bug 
    opened by hamed8080 0
  • Feat:  New plugin flag for skipping synthesized symbols

    Feat: New plugin flag for skipping synthesized symbols

    Bug/issue #, if applicable: #27

    Summary

    This pull request aims to support the generation of archives without synthesized symbols by passing a new plugin flag --skip-synthesized-symbols. This would reduce the size of the generated doccarchive.

    The plugin flag --skip-synthesized-symbols has been added to achieve this. It doesn't transform any of the passed arguments but overrides the default value of symbolGraphOptions.includeSynthesized to false. Also, with the proposed implementation, more flags could be added to override other settings of the symbol graph options.

    Dependencies

    N/A

    Testing

    For automated testing run the integration tests suite.

    For manual testing:

    1. Download the attached package
    2. In Package.swift set the right path for swift-docc-plugin dependency
    3. Run swift package generate-documentation, and swift package generate-documentation --skip-synthesized-symbols, for both compare the files generated at PackageWithConformanceSymbols.doccarchive/data/documentation/packagewithconformancesymbols/bar

    PackageWithConformanceSymbols.zip

    Checklist

    Make sure you check off the following items. If they cannot be completed, provide a reason.

    • [X] Added tests
    • [X] Ran the ./bin/test script and it succeeded
    • [ ] Updated documentation if necessary
    opened by sofiaromorales 0
  • Support for skipping synthesized symbols

    Support for skipping synthesized symbols

    Feature Request: Support for skipping synthesized symbols

    Description:

    The Swift compiler supports a -skip-synthesized-members argument which excludes synthesized symbols from symbol graph files. Synthesized symbols can lead to a large increase in number of documentation pages for some frameworks. We should have a way of generating documentation without synthesized symbols from the DocC plugin.

    enhancement good first issue 
    opened by franklinsch 1
  • Provide sensible defaults when using `--source-service` argument

    Provide sensible defaults when using `--source-service` argument

    docc added support for specifying information about the remote source repository where the project is hosted (e.g., its GitHub URL) in https://github.com/apple/swift-docc/pull/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.

    enhancement 
    opened by franklinsch 0
Releases(1.0.0)
Cordova-plugin-saveimage - This plugin helps you save images

cordova-plugin-saveimage This plugin helps you save images on iOS/Android Instal

Bernat 2 May 11, 2022
API surface for Swift plug-ins using the Swift Plugin Manager

SwiftPlugin The minimal API surface required for the Swift Plugin Manager to create instances from a loaded plugin. Additional documentation and refer

Joakim Hassila 2 Mar 25, 2022
PerFolderResourcesPublishPlugin - Per-folder resources plugin for the Publish package

Per-folder resources for Publish A Publish plugin that copies per-folder resourc

Tom Harrington 1 Feb 18, 2022
A VisionCamera Frame Processor plugin for fast buffer resizing

vision-camera-resize-plugin A VisionCamera Frame Processor Plugin for fast buffer resizing. By resizing buffers to a smaller resolution, you can achie

Marc Rousavy 16 Aug 10, 2022
This simple cordova plugin will download picture from an URL and save to IOS Photo Gallery.

Photo Viewer This plugin is intended to download a picture from an URL into IOS Photo library.. How to Install Cordova: cordova plugin add https://git

Alwin jose 1 Oct 23, 2021
Cordova plugin for detect screenshots and recordings

cordova-plugin-detect-screen-capture This plugin detects screen recording and screenshot events. The plugin will only work on devices with iOS >= 7 Su

Sasha 0 Nov 4, 2021
Cordova plugin to display a native color-picker dialog

Color Picker Plugin for Cordova (cordova-plugin-color-picker) Description This plugin allows you to display a color-picker native dialog in iOS and An

Antonio Vargas 1 May 10, 2022
Metazoom - A virtual camera plugin to pixellatedly share your screen

MetaZoom A virtual camera plugin to pixellatedly share your screen. See LICENSE.

Sahil Lavingia 20 Apr 19, 2022
Flutter openvpn - A new Flutter plugin that uses OpenVpn

flutter_openvpn A new Flutter plugin that uses OpenVpn. Installation Depend on i

Ferdi Gökdemir 0 Jan 8, 2022
Xcode plugin that moves the instruction pointer to the selected line

SFJumpToLine Xcode plugin that moves the instruction pointer to the selected line. Install: Install via Alcatraz Or clone and build the project, then

Simone Ferrini 9 Jan 14, 2021
Touch ID Plugin (Cordova) for iOS

cordova-plugin-gctouch-id Touch ID Plugin (Cordova) for iOS Author: Giulio Caruso aka rdn Index Description Technical Documentation Screenshots Adding

Giulio Caruso 20 Jan 3, 2022
Xcode plugin that brings ⇧⌘T from AppCode over to Xcode

Aviator An Xcode Plugin that brings ⇧⌘T over to Xcode This minimal plugin allows you to use the key combo ⇧⌘T to toggle between source and test files.

Mark Sands 29 Aug 18, 2018
An Xcode plugin for manually symbolicating crash logs

CrashSymbal An Xcode plugin for manually symbolicating crash logs Install Build the project to install the plugin. The plugin gets installed in /Libra

Julian F. Weinert 38 Jun 3, 2021
A Xcode plugin to add highlight to the instances of selected symbol.

Auto Highlight Symbol About Xcode 8 Xcode 8 does't support plugins anymore, but there is a workaround, use at your own risk. Xcode can highlight insta

Nelson 83 Jun 17, 2022
XcodeColorSense - An Xcode plugin that makes working with color easier.

XcodeColorSense An Xcode plugin that makes working with color easier. Inspired by ColorSense-for-Xcode with extra care for Hex color Features Show col

Khoa 77 Jul 1, 2022
An Xcode 7 plugin to build and run an app across multiple iOS devices with one click.

RunEverywhere Xcode Plugin Overview An Xcode 7 plugin to build and run an app across multiple iOS devices with one click. Gone are the days of manuall

Eric Mika 322 Sep 7, 2022
Xcode plugin to open the GitHub page of the commit of the currently selected line in the editor window.

Show in GitHub / BitBucket Xcode plugin to open a related Github or BitBucket page directly from the Xcode editor code window. Installs easily through

Lars Schneider 242 Jul 20, 2022
An Xcode plugin to improve dealing with colors in your project

Crayons is an Xcode7 plugin with various features that improve working with colors in your projects ##Code palettes (iOS only) You can share palettes

Fabio Ritrovato 478 Jun 29, 2022
The repository for a command line / build pipeline tool for generating colors from a human-readable text file that designers can also use.

ColorPaletteGenerator ColorPaletteGenerator is a tool that takes a human-readable input file describing a color palette, and generates the associated

horseshoe7 0 Dec 7, 2021