apple / swift-docc Goto Github PK

Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.

Home Page: https://swift.org/documentation/docc

License: Apache License 2.0

Dockerfile 0.01% Swift 99.35% HTML 0.11% Shell 0.30% Python 0.21% Objective-C 0.02%

swift-docc's Introduction

Swift-DocC

Swift-DocC is a documentation compiler for Swift frameworks and packages aimed at making it easy to write and publish great developer documentation

For an example of Swift-DocC in action, check out developer.apple.com. Much of Apple's developer documentation, from Reference documentation to Tutorials, and long-form content is built using Swift-DocC.

To learn more about the essentials of this tool refer to the user documentation.

Swift-DocC is being actively developed. For more information about the Swift-DocC project, see the introductory blog post here.

Getting Started with DocC

docc is the command line interface (CLI) for Swift-DocC and provides support for generating and previewing documentation.

There are multiple ways you can make use of DocC depending on your use case:

1. For documenting packages via SwiftPM:

If you want to generate documentation for your Swift package we recommend using the Swift-DocC Plugin. Please refer to the Plugin's documentation to get started with building, previewing, and publishing your documentation to your website or GitHub Pages.

2. For standalone documentation:

If you have Xcode installed, it's recommended to generate documentation using the xcrun command. You can get DocC working by invoking xcrun docc in your terminal.

Swift-DocC is also included in the Swift toolchain for both macOS and Linux.

To see instructions on how to use DocC from the CLI run

docc --help

3. For documenting apps, frameworks, and packages using Xcode:

If you want to generate an API reference for your project you can use DocC via Xcode. Please refer to the Xcode documentation to learn the essentials of how to get started.

Writing and Publishing Documentation with Swift-DocC

If you want to learn how to write and format your documentation please refer to Formatting Your Documentation Content. For publishing go to Distributing Documentation to Other Developers.

To learn more about how Swift-DocC works internally please see CONTRIBUTING.md.

Versioning

Swift-DocC's CLI tool (docc) is integrated into the Swift toolchain and follows the Swift compiler's versioning scheme.

The SwiftDocC library is versioned separately from docc. SwiftDocC is under active development and source stability is not guaranteed.

Bug Reports and Feature Requests

Submitting a Bug Report

Swift-DocC tracks all bug reports with GitHub Issues. When you submit a bug report we ask that you follow the provided template and provide as many details as possible.

Note: You can use the environment script in this repository to gather helpful environment information to paste into your bug report by running the following:
bin/environment

If you can confirm that the bug occurs when using the latest commit of Swift-DocC from the main branch (see Building Swift-DocC), it will help us track down the bug faster..

Submitting a Feature Request

For feature requests, please feel free to file a GitHub issue or start a discussion on the Swift Forums.

Don't hesitate to submit a feature request if you see a way Swift-DocC 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 Swift-DocC

The Swift Forums are the best place to get help with Swift-DocC and discuss future plans.

As an open-source project, we value any contribution made to this tool. Please see the contributing guide for more information on how to contribute and build DocC from source.

swift-docc's People

Contributors

Stargazers

Watchers

Forkers

hassila kaandedeoglu phuhuynh2411 finagolfin maldahleh geraldoluoch z3season franklinsch quietmisdreavus atierian ethan-kusters nyangoto wptechprodigy wiramahendra allensmile d-ronnqvist bitjammer mportiz08 etcwilde wowbaggersliquidlunch zbencz3 proffan domandinho karwa vitonzhangtt classicvalues shenyj kyle-ye pollcastillo themomax tachoknight heckj tiagomaial bricker rintaro bitcoinlegends59 atthisaccount kimdv ixerol binamaniar jerryedensjr daniel-grumberg adellibovi talzag hrishidev jackhl isabella232 debugsteven nickmain clarkguan johnmckerrellav lawgimenez icanzilb thanvanthanh mayaepps finestructure kdaud denil-ct silvrwolfboy test-mass-forker-org-1 dempseyatgithub tryweirdier stephencelis berchan nexuspcs arthurcro jwarrendev armbiant oksusucha dobromir-hristov davidperezp124 starcomsys nithintummala gg-big-org danielle-snyk stzn sonyeric claire3628 kajornsakp mvvsmk pdwilson12 pcjbird sofiaromorales ferencios niodebacker compnerd limchihi emilyychenn natikgadzhi dsp-testing raul-ramirezl darshilmakwan tomstuart zunda-pixel patshaughnessy anthony-eid bedlam520 kkpan11 pshadov yonihemi

swift-docc's Issues

[SR-15753] Properly export top-level decls from @_exported import modules into the symbol graph


Previous ID	SR-15753
Radar	rdar://89547374
Original Reporter	@QuietMisdreavus
Type	Improvement
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	@franklinsch
Priority	Medium

md5: 3036c7fd1b6ab90027e1cf5a38812878

Issue Description:

While investigating apple/swift#40860, i noticed that symbols from @_exported import are not getting included in the symbol graph file of the module that imports them. Since these symbols are part of the module's API, its symbol graph file should contain them.

[SR-15311] [Swift-DocC] Add support for SVG and GIF as image types


Previous ID	SR-15311
Radar	rdar://48248137
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 6fc7ba10fc4d9b5b2439ada7f96a8f5c

Issue Description:

Swift-DocC currently ignores SVG and GIF files. We should add support for recognizing them as images in the same we do for JPEG, JPG, and PNG files.

[SR-15408] Building documentation with a fallback display name that includes a space produces a broken-looking article


Previous ID	SR-15408
Radar	rdar://84810134
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Attachment: Download

Environment

Reproduced with commit hash ba393152de75579fe4c60a8d7da2b3a719c31998 on the main branch.

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, StarterBug
Assignee	@d-ronnqvist
Priority	Medium

md5: bd37b05faf06107586133ec6b88d0a65

Issue Description:

If I pass a fallback display name with a space (like --fallback-display-name "My Display Name") to docc, along with a valid symbol graph, DocC generates an article with ``My Display Name`` as the H1 heading and organizes it under an “Articles” topic group on my top-level framework page. I don’t expect this article to be created at all.

Reproduction Steps:

Download the attached symbol graph
Run the following:

docc preview --fallback-display-name "Tiny Framework" --fallback-bundle-identifier TinyFramework --fallback-bundle-version 1 --additional-symbol-graph-files /path/to/Tiny_Framework.symbols.json

[SR-15315] [Swift-DocC] @Image directive requires an explicit file extension while images described in Markdown do not


Previous ID	SR-15315
Radar	rdar://79140625
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Attachment: Download

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: c536abd6e1f81618ac79693f894f0da9

Issue Description:

Swift-DocC generally allows users to describe images with just the filename (ImageName), leaving out the file extension (.png).

For example, if a user included ImageName.png in their documentation catalog, they could refer to it with:

![Image description](ImageName)

However, when referencing images in Tutorials using the @image directive, DocC requires users to be explicit and use the file extension:

@Image(source: "ImageName.png", alt: "Image description")

This is confusing, so we should allow the following syntax:

@Image(source: "ImageName", alt: "Image description")

[SR-15754] Override merge behaviour removes all Xcode popover documentation


Previous ID	SR-15754
Radar	None
Original Reporter	@karwa
Type	Bug

Attachment: Download

Environment

macOS 11.6, Xcode 13.2.1 (13C100)

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: ee66e5044a4c31ce0a974d83ef42f904

Issue Description:

In my package, I have a type which is documented via a markdown extension doc. This looks great in the documentation browser, but I also want to provide great documentation in the Xcode alt+click popover.

Currently, the default appears to append the source docs with the extension docs, meaning I need to limit the popover docs to just the first line:

Code:

Popover:

Documentation browser (notice the summary up top comes from the source docs):

Now, if I extend the source docs with a longer (yet still abbreviated) summary, I get a better popover experience, but the documentation browser duplicates it, with 2 overview sections:

Popover:

Documentation browser:

Now, if I add specify the "override" merge behaviour in the markdown document, I can remove the duplicated content in the documentation browser, but now get absolutely no popover documentation at all, despite there obviously being documentation which you can see in the background.

This means I'm not able to provide a great popover and documentation browser experience simultaneously 🙁

[SR-15407] DocC (wrongly) renders actors as classes


Previous ID	SR-15407
Radar	rdar://84751310
Original Reporter	@ktoso
Type	Bug

Attachment: Download

Environment

Nightly `main` toolchain from October 27th

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	@QuietMisdreavus
Priority	Medium

md5: 314cf0c884190d9ab14edc3fb2ab9753

Issue Description:

Summary:
Actors are listed as classes under the Classes: section. This is very confusing, they should be listed as their own category as they are stand alone nominal types.

Steps To Reproduce:

Declare an actor public actor NEIN {}

Results:
Actor shows up under classes as class NEIN which is misleading.

Expected:
Should get their own section.

Extra:
And distributed actors should get their own section as well, perhaps under actors?

[SR-15320] [Swift-DocC] Support file monitoring and live updating for `docc preview` on Linux


Previous ID	SR-15320
Radar	rdar://81741255
Original Reporter	@ethan-kusters
Type	Bug

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: 61fada8d285df1475577ed7e32a4df5e

Issue Description:

When run on macOS, the docc command-line tool monitors the given documentation catalog and automatically re-converts it upon changes. We should add support for this feature on Linux as well.

[SR-15345] [Swift-DocC] Test fail on non-English locale machine


Previous ID	SR-15345
Radar	None
Original Reporter	@Kyle-Ye
Type	Bug
Status	Resolved
Resolution	Done

Attachment: Download

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	@Kyle-Ye
Priority	Medium

md5: 49de6cc6c7ad3340d0b88fa6b4180813

Issue Description:

Currently some test file in DocC like SemaToRenderNodeTests.swift have the following test expression.

```

XCTAssertEqual(firstTutorialReference.estimatedTime, "20 min")

```

The estimatedTime's implementation use DateComponentsFormatter. And will localize the time text according to the locale. While the test assume the English locale and use the raw string to compare.

[SR-15312] [Swift-DocC] Add 'version' command to docc command line tool


Previous ID	SR-15312
Radar	rdar://58842647
Original Reporter	@ethan-kusters
Type	Bug
Status	Closed
Resolution	Invalid

Additional Detail from JIRA


Votes	1
Component/s	Swift-DocC
Labels	Bug, StarterBug
Assignee	None
Priority	Medium

md5: 765556f0235e43786ce452dab96df62e

Issue Description:

docc should output it's current version to the command line.

This could be similar to the behavior of the `swift --version` command and output the current version of `docc` along with a commit hash.

[SR-15319] [Swift-DocC] Remove diagnostic for use of "topic://" links


Previous ID	SR-15319
Radar	rdar://71579947
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 760938bf92615d19d1cca70e88f88e58

Issue Description:

Swift-DocC used to allow <doc:> style links to be written as <topic:> links. We no longer support this old syntax and all warnings related to it should be removed.

[SR-15828] DocC should have an option to add links from docs to source


Previous ID	SR-15828
Radar	rdar://problem/88537303
Original Reporter	@weissi
Type	New Feature

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	New Feature
Assignee	None
Priority	Medium

md5: 8a1592f84ad3c14de454f037655f6bec

Issue Description:

For open-source software it makes so much sense to have the documentation have a link that jumps straight to the sources (on Github or so). That way the source can complement the documentation and users also have an easy way to propose improve docs straight from github.

Forums discussion here: https://forums.swift.org/t/links-to-sources-in-generated-documentation/55134

[SR-15349] [Swift-DocC] Failing SemaToRenderNodeTests tests


Previous ID	SR-15349
Radar	None
Original Reporter	maldahleh (JIRA User)
Type	Bug
Status	Closed
Resolution	Duplicate

Environment

M1 Mac Mini

code as of commit: ff972f1

swift --version:

swift-driver version: 1.26.9 Apple Swift version 5.5 (swiftlang-1300.0.31.1 clang-1300.0.29.1)
Target: arm64-apple-macosx11.0

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	@Kyle-Ye
Priority	Medium

md5: 84033af5a23b1a72c09b3fcb000b4e64

Issue Description:

Running `./bin/test` produces:

/Users/maldahleh/Documents/swift/swift-docc/Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift:896: error: -[SwiftDocCTests.SemaToRenderNodeTests testCompileOverviewWithVolumes] : XCTAssertEqual failed: ("Optional("20 min.")") is not equal to ("Optional("20min")")
/Users/maldahleh/Documents/swift/swift-docc/Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift:902: error: -[SwiftDocCTests.SemaToRenderNodeTests testCompileOverviewWithVolumes] : XCTAssertEqual failed: ("Optional("1 hr. 20 min.")") is not equal to ("Optional("1hr 20min")")
Test Case '-[SwiftDocCTests.SemaToRenderNodeTests testCompileOverviewWithVolumes]' failed (0.220 seconds).

The tests are expecting the `estimatedTime` without periods, while the `estimatedTime` string includes periods.

[SR-15543] Support named sections in "See Also"


Previous ID	SR-15543
Radar	None
Original Reporter	@karwa
Type	Improvement

Attachment: Download

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	None
Priority	Medium

md5: 2d2ee8c4683c068b8df5d8b269804f70

Issue Description:

Currently, "See Also" sections cannot have named sub-sections, and all referenced symbols are grouped in a "Related Documentation" group.

It would be nice to have the opportunity to explain how a referenced symbol is related to the one the user is currently viewing.

Swift forums thread: https://forums.swift.org/t/named-groups-in-see-also/53776

Currently:

Desired (this is using Topics to give the desired presentation, but really it's an abuse of Topics):

[SR-15434] [Swift-DocC] Support custom documentation module kinds


Previous ID	SR-15434
Radar	rdar://83448323
Original Reporter	@ethan-kusters
Type	Improvement
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	2
Component/s	Swift-DocC
Labels	Improvement
Assignee	@ethan-kusters
Priority	Medium

md5: 6206e14f17a5fa158306a795d8f034f6

Issue Description:

Swift-DocC currently describes every documentation catalog it produces as a “Framework”.

For example, DocC’s own user-facing documentation at https://swift.org/documentation/docc/ is currently incorrectly described as a “Framework”.

While SwiftDocC is a framework, the documentation hosted at https://swift.org/documentation/docc/ is documentation explaining how to use DocC as a tool; it is not documentation of the SwiftDocC framework.

Swift-DocC should be enhanced to allow documentation authors to provide custom text to describe the thing they are documenting. This should allow the DocC user-facing documentation to describe itself as a “Documentation Tool” instead of as a “Framework”. This should also allow for build systems that integrate with DocC to accurately produce documentation for other product types, like executables.

[SR-15750] [Swift-DocC] `docc archive transform-for-static-hosting` should add support for experimental custom header/footer feature


Previous ID	SR-15750
Radar	rdar://problem/87740373
Original Reporter	@ethan-kusters
Type	Improvement

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	None
Priority	Medium

md5: 717260373b6916638ec4326a5b4138a8

cloned from:

SR-15576 [Swift-DocC] Transform-for-static-hosting does not DocC's experimental custom header/footer feature

relates to:

SR-15576 [Swift-DocC] Transform-for-static-hosting does not DocC's experimental custom header/footer feature

Issue Description:

Currently the `docc archive transform-for-static-hosting` action does not respect the experimental header/footer that can be provided in a DocC Catalog.

Note that this bug is specifically tracking support for transforming a pre-built archive that made use of the experimental header/footer feature. Support for picking up an experiemental header/footer as part of the initial conversion is tracked with SR-15576.

The implementation of this would add a new --experimental-enable-custom-templates flag to docc archive transform-for-static-hosting.

[SR-15317] [Swift-DocC] Emit a warning for a "See Also" task group within a Topics section.


Previous ID	SR-15317
Radar	rdar://60684559
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 963ca050244e96619e8c563b137ddc6e

Issue Description:

It's easy to accidentally write a "See Also" section as part of a Topics section (like the following) instead of as it's own second-level heading like DocC expects:

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

### See Also

- ``RelatedSymbol``

However, DocC requires See Also sections to be written as second-level headings beneath a Topics section, not as subsections of Topics sections. DocC should emit a warning with a fixit upon encountering this. In this case, the fixit would update the example to the following:

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

## See Also

- ``RelatedSymbol``

[SR-15576] [Swift-DocC] Transform-for-static-hosting does not DocC's experimental custom header/footer feature


Previous ID	SR-15576
Radar	rdar://problem/86298113
Original Reporter	@ethan-kusters
Type	Bug

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: c735028a1eb87105ac679771fac32b43

cloned to:

SR-15750 [Swift-DocC] docc archive transform-for-static-hosting should add support for experimental custom header/footer feature

relates to:

SR-15750 [Swift-DocC] docc archive transform-for-static-hosting should add support for experimental custom header/footer feature

Issue Description:

Currently the `transform-for-static-hosting` action does not respect the experimental header/footer that can be provided in a DocC Catalog.

Since `transform-for-static-hosting` is still experimental, this lack of support did not block landing the initial implementation but it should be fixed for user's who want to host their docs in a static environment and take advantage of the experimental custom header/footer support.

The basics of what are needed to add support can be found here: ethan-kusters@119770f.

[SR-15316] [Swift-DocC] Emit a warning when a Topics section is written without a subheading


Previous ID	SR-15316
Radar	rdar://58875480
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	maldahleh (JIRA)
Priority	Medium

md5: 1e9985f00dbb5c1b1959ca90b9b4237a

Issue Description:

Swift-DocC requires all Topics sections to include at least one subheading or it drops the Topics section altogether. If Swift-DocC encounters a Topics section with no subheadings during compilation, a warning should be emitted to help users understand why their content is not being rendered.

[SR-15575] [Swift-DocC] Further refine `transform-for-static-hosting` implementation based on PR feedback


Previous ID	SR-15575
Radar	rdar://problem/86298119
Original Reporter	@ethan-kusters
Type	Improvement

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	None
Priority	Medium

md5: 8bd44f66cd04ad973a1c0dca10e51092

Issue Description:

During the review of #44 we received some valuable feedback that should be addressed but we didn't feel should block landing the initial implementation.

Here are some key points:

Refactor some of the new symbol names to better explain what they're for and align with Swift API guidelines: https://www.swift.org/documentation/api-design-guidelines/
- This is likely something we can do across the SwiftDocCUtilities library, beyond what was introduced in this PR.
- #44 (comment)
Consider replacing direct string manipulation of paths in StaticHostableTransformer with a URLComponents
- #44 (comment)
Refactor StaticHostableTransformer to use a more generic file walking type that can be shared in DocC. We have similar file walking behavior in the `Index` action so we should be able to re-use this code.
- #44 (comment)

[SR-15318] Host Swift-DocC documentation on Swift.org


Previous ID	SR-15318
Radar	rdar://84211899
Original Reporter	@franklinsch
Type	New Feature
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	New Feature
Assignee	@franklinsch
Priority	Medium

md5: 7011eb0a62e54c7e74c8a037c3247e1e

Issue Description:

This tracks work to host documentation for the Swift-DocC project on swift.org/documentation.

[SR-15556] Duplicate conformance sections generated from synthesized conformance in Docc


Previous ID	SR-15556
Radar	rdar://problem/86089651
Original Reporter	@heckj
Type	Bug

Attachment: Download

Environment

Happens with both Xcode 13.1 and Version 13.2 beta 2 (13C5081f)

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC, Swift-DocC-Render
Labels	Bug
Assignee	None
Priority	Medium

md5: deb5998f8c142585ed2da631bc6fe8b3

Issue Description:

I'm not certain where the duplication comes from - but when I'm working on documenting a struct that has synthesized conformances, I'm seeing some replicated "Default Implementations" sections with the various operators.

The specific case that illustrates this is a struct that has an extenion where it conforms to Comparable. For detail, an example struct:

```
public struct ObjectId: Equatable, Hashable, Codable, ExpressibleByStringLiteral, ExpressibleByStringInterpolation {

init(_ objectId: String = UUID().uuidString)

{ self.objectId = objectId }

let objectId: String

public init(from decoder: Decoder) throws

{ let container = try decoder.singleValueContainer() self.objectId = try container.decode(String.self) }

public func encode(to encoder: Encoder) throws

{ var container = encoder.singleValueContainer() try container.encode(objectId) }

static let root: ObjectId = "_root"
static let head: ObjectId = "_head"

public init(stringLiteral value: StringLiteralType)

{ self.objectId = value }

func parseOpId() -> (counter: Int, actorId: String)? {
guard objectId.contains("@") else

{ return nil }

let splitted = objectId.split(separator: "@")
return (counter: Int(String(splitted[0]))!, actorId: String(splitted[1]))
}
}

extension ObjectId: Comparable {
public static func < (lhs: ObjectId, rhs: ObjectId) -> Bool

{ return lhs.objectId < rhs.objectId }

}
```

The resulting documentation exposed (through Xcode, or `docc-preview` on the CLI) shows the attached screenshot. Within each of the sections listed as 'Implementations' with nothing preceding it, are the same operators- screenshot of those attached as well. They're all from Comparable:
```
static func ... (Self) -> PartialRangeThrough<Self>
static func ... (Self) -> PartialRangeFrom<Self>
static func ... (Self, Self) -> ClosedRange<Self>
static func ..< (Self) -> PartialRangeUpTo<Self>
static func ..< (Self, Self) -> Range<Self>
```

[SR-15574] Create LinkDestinationSummary content variants for all source languages


Previous ID	SR-15574
Radar	rdar://problem/86298116
Original Reporter	@d-ronnqvist
Type	Improvement
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	@d-ronnqvist
Priority	Medium

md5: 78aff46d658bb3269a2b475493b50ec6

Issue Description:

The changes in Swift-Docc PR updated the linkable entities spec to support multi-language data. It also updated the implementation to follow the the format of the new spec but it's still only writing the content for the documentation node's sourceLanguage property, not for all the available source languages.

As a follow up change we should update the implementation to write the content variants for all available source languages.

[SR-15316] [Swift-DocC] Emit a warning when a Topics section is written without a subheading


Previous ID	SR-15316
Radar	rdar://58875480
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	maldahleh (JIRA)
Priority	Medium

md5: 1e9985f00dbb5c1b1959ca90b9b4237a

Issue Description:

[SR-15372] DocC should allow versions of the legal "pre release" sem-ver formats (e.g. 1.2.3-SNAPSHOT)


Previous ID	SR-15372
Radar	rdar://84540229
Original Reporter	@ktoso
Type	Improvement
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	@d-ronnqvist
Priority	Medium

md5: a25eaf2250be7d1a8408bf0c3d46e8a1

Issue Description:

1. Current behavior:
  DocC rejects versions like 1.2.3-dev / 1.2.3-SNAPSHOT

Specifically it errors like this:

Error: '0.6.5-dev' is not a valid version string

1. Expected behavior:

Some libraries, may want to make available docs for their nightly builds which are not tagged with “stable” versions but use some suffix like -SNAPSHOT or -dev.
In the server ecosystem we often have libraries stay around as -alpha or -beta or -dev for a while before they stabilize their APIs, but we DO want to be able to use them while in this state.

SwiftPM recognizes these versions and allows depending on them.

Specifically this is covered by sem-ver rule 9:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–.

I started poking at this, but sem-ver is actually quite a pain to parse properly manually.
Perhaps we should re-use code that SwiftPM has for this actually? I'll search around a little bit

[SR-15634] Remove need to pass `--fallback-...` CLI arguments in most cases


Previous ID	SR-15634
Radar	rdar://problem/86819483
Original Reporter	@d-ronnqvist
Type	Improvement

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement, StarterBug
Assignee	waheedNowLovesSwift (JIRA)
Priority	Medium

md5: 675dc1ff1939386d0c186c42c940543c

Issue Description:

Swift-DocC requires some minimal information about the documentation that it's building to name and identify the documentation. This information can be specified in a couple of different ways:

If the documentation has a DocC catalog (a folder with a .docc extension) with an Info.plist file in it, then the documentation's name and identifier can be read from the content of that identifier.
If the documentation doesn't have a DocC catalog, or the catalog doesn't have an Info.plist file, then the documentation's name and identifier can be provided as two command line arguments (----``fallback-display-name and --``fallback-bundle-identifier). These arguments are prefixed with "fallback" because they are only used when a value can't be retrieved from the DocC catalog's Info.plist file (for example if that file doesn't exist).

The documentation's identifier doesn't need to follow a specific format. That said, the identifier needs to be unique to the current documentation build. In almost all cases documentation is built separately for each "bundle", so uniqueness isn't an issue. Further, even when multiple "bundles" are built together their display name are most often unique enough.

A documentation "bundle" is the term for the in-memory representation about a framework or other project. One DocC catalog corresponds to one documentation bundle, but a bundle can also be created from the module information in symbol graph files when there's no DocC catalog.

Because of this, a suitable documentation identifier can almost always be derived from the documentation's display name. When that derived identifier isn't unique, this can be identified and diagnosed and that issue can be resolved by providing a unique identifier either as an Info.plist value or as a custom --``fallback-bundle-identifier argument.

Further, a suitable documentation display name can almost always be derived from other information in the documentation "bundle". A documentation bundle consist of either a DocC catalog or a collection of symbol graph files, or both.

Most documentation is about a single module. In this case, when all the bundle's symbol graph files are about the same module, then that module name is a good display name in almost all cases. When it's not, a custom name can be provided as a --fallback-display-name argument.

If the bundle contains symbol graph files about more than one module or if the bundle doesn't contain any symbol graph files, then it's less clear what a good display name would be. However, since the developer need to provide a custom display name if none is derived but only needs to provide a custom display name if the derived one is incorrect, I feel that deriving a display name that's good enough in many cases still provide value here. In this situation, I feel that deriving the documentation from the DocC catalogs filename (without the file extension) is likely to be a good enough value in many cases.

Since the documentation's version information is already optional, making the above changes to derive the documentation's identifier and display name would remove most of the cases when developer's need to pass --fallback... CLI arguments.

Summary

If a documentation bundle has no specified identifier, derive the identifier from the bundle's display name.

If a documentation bundle has no specified display name:

and it has symbol graph files about a single module, derive the display name from the module's name
and it has a DocC catalog, derive the display name from the catalog's filename (without the file extension)
otherwise (if the bundle has no DocC catalog and symbol graphs about multiple modules, raise the same error as today that a display is missing name and needs to be provided.

[SR-15540] Documentation coverage "USR" column is named incorrectly


Previous ID	SR-15540
Radar	None
Original Reporter	@franklinsch
Type	Bug

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: 03bfd579fe69e2e3c621d898704baf08

Issue Description:

When compiling documentation with the experimental documentation support enabled, the coverage data that's emitted includes a column called "USR". The naming is incorrect because the values that DocC emits is actually the documentation links of the generated pages, rather than their USR (the USR is a compiler-generated unique string that identifies a symbol). The column should be named to something like "Documentation Link" instead.

[SR-15319] [Swift-DocC] Remove diagnostic for use of "topic://" links


Previous ID	SR-15319
Radar	rdar://71579947
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 760938bf92615d19d1cca70e88f88e58

Issue Description:

Swift-DocC used to allow <doc:> style links to be written as <topic:> links. We no longer support this old syntax and all warnings related to it should be removed.

[SR-15314] [Swift-DocC] Improve help information for `docc index` command


Previous ID	SR-15314
Radar	rdar://68701016
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, StarterBug
Assignee	maldahleh (JIRA)
Priority	Medium

md5: c4c6583d1092b3d462a1a4eacca43836

Issue Description:

The help information emitted for the docc index subcommand instructs the user to provide a .docc catalog as input. The command actually expects a Data folder of render JSON files from a compiled documentation archive. We should update the help information to reflect this.

Currently this is what docc emits for ‘docc index --help’:

OVERVIEW: Create an index for the documentation from compiled data.

USAGE: docc index <source-bundle-path> -bundle-identifier <bundle-identifier> [-verbose]

ARGUMENTS:
<source-bundle-path> Path to a documentation bundle directory.
The '.docc' bundle docc will build.

[SR-15541] Support hosting of multiple DocC archive(s) (versions)


Previous ID	SR-15541
Radar	None
Original Reporter	sean.labastille (JIRA User)
Type	New Feature

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	New Feature
Assignee	None
Priority	Medium

md5: d8b94f21136b90a125e8e8af7be04f87

Issue Description:

Hosting a single documentation archive is relatively straightforward and well-documented

However, when attempting to host multiple versions of documentation for the same module name it seems that the default routing doesn't work as this relies on the resources being at certain paths relative to the root of the server.

I could imagine a general "prefix" mechanism allowing a prefix to all of these paths being specified could help enable this use case and others where several documentation archives are hosted on one host without needing to adjust URL rewriting rules.

[SR-15722] Include information about @MainActor in the symbol graph


Previous ID	SR-15722
Radar	None
Original Reporter	kap (JIRA User)
Type	Improvement

Additional Detail from JIRA


Votes	1
Component/s	Swift-DocC
Labels	Improvement
Assignee	kap (JIRA)
Priority	Medium

md5: e865b78877f6833c45e5909a5be1026c

Issue Description:

The current implementation of -emit-symbol-graph does not include any of the custom attributes, which, in turn, does not enable DocC (and the generated documentation) to document when a symbol is marked with @MainActor.

While all of the custom attributes are skipped (e.g. property wrappers, global actors), allowing @MainActor to be emitted into the symbol graph would be a nice start.

Forum thread discussing this

[SR-15414] DocC can't refer to Identifiable `id` property


Previous ID	SR-15414
Radar	None
Original Reporter	rnikander (JIRA User)
Type	Bug

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: c52b0f49f42bf64ff30b67f218f38502

Issue Description:

I noticed this in a more complicated situation, when I could not put my id property in my Topics section, to control where it appears. The following is a boiled down example. I included CustomStringConvertible and description, because oddly DocC is fine with that one.

/// I can't talk about  ``id`` but I can talk about ``description``. 
public struct FooBar: CustomStringConvertible, Identifiable {
    /// doc 1
    public var id: String
    /// doc 2
    public var foo: Int
    /// doc 3
    public var description: String
}

The compiler does not like the ``id``. It says:

Topic reference 'id' couldn't be resolved to known documentation

The rendered documentation has a nice link for description but not for id.

[SR-15431] Support DocC references to symbols defined in another module


Previous ID	SR-15431
Radar	rdar://79049385
Original Reporter	@Mordil
Type	New Feature

Additional Detail from JIRA


Votes	19
Component/s	Swift-DocC
Labels	New Feature
Assignee	None
Priority	Medium

md5: c3c52c8ed342d1b0fea2c443bcf8f543

Issue Description:

As a database driver author, I rely heavily on SwiftNIO for the architecture of my driver, and users of my driver should be familiar with many of the concepts and types defined by SwiftNIO that I also expose.

When I write symbol documentation or articles, I would like the ability to reference those types, to enrich the exploration of documentation with Xcode.

The syntax I would find the least surprising is having to prepend the module's name at the start, such as ``SlothCreator/Habitat``

[SR-15319] [Swift-DocC] Remove diagnostic for use of "topic://" links


Previous ID	SR-15319
Radar	rdar://71579947
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 760938bf92615d19d1cca70e88f88e58

Issue Description:

Swift-DocC used to allow <doc:> style links to be written as <topic:> links. We no longer support this old syntax and all warnings related to it should be removed.

[SR-15779] Swift 5.6 nightly build missing the 'index-template.html' file


Previous ID	SR-15779
Radar	None
Original Reporter	@heckj
Type	Bug
Status	Closed
Resolution	Invalid

Environment

```

/Library/Developer/Toolchains/swift-5.6-DEVELOPMENT-SNAPSHOT-2022-01-11-a.xctoolchain/usr/bin/swift --version
Apple Swift version 5.6-dev (LLVM 64a4d678f114158, Swift 8ae983c3480462b)
Target: arm64-apple-macosx12.0

```

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: c68732becdc37b3ee26d418f6672de64

Issue Description:

I was experimenting with the upcoming static hosting feature for some current documentation, using the Jan 11th 5.6 nightly toolchain `/Library/Developer/Toolchains/swift-5.6-DEVELOPMENT-SNAPSHOT-2022-01-11-a.xctoolchain`

When running `docc convert` to generate a statically hosted site, it's returning the error:
`The directory at '/Library/Developer/Toolchains/swift-5.6-DEVELOPMENT-SNAPSHOT-2022-01-11-a.xctoolchain/usr/share/docc/render' does not contain a valid template. Missing 'index-template.html' file.`

I checked the swift nightly toolchain, and it does have this file, but the latest swift 5.6 nightly doesn't:
```
find /Library/Developer/Toolchains -name "index-template.html"
/Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-2022-01-09-a.xctoolchain/usr/share/docc/render/index-template.html
```

I suspect that the associated render artifact needs to be regenerated, or a different version included into the toolchain build process. The repository branch for swift-docc-render-artifact does appear to include the file: `https://github.com/apple/swift-docc-render-artifact/tree/release/5.6/dist\`

[SR-15352] Support for localizing Swift-DocC content


Previous ID	SR-15352
Radar	rdar://83885088
Original Reporter	@franklinsch
Type	New Feature

Additional Detail from JIRA


Votes	1
Component/s	Swift-DocC
Labels	New Feature
Assignee	None
Priority	Medium

md5: 1f924c6107b7f47dadaebde9c7c5da24

Issue Description:

Tracks support for writing localized Swift-DocC documentation.

[SR-15316] [Swift-DocC] Emit a warning when a Topics section is written without a subheading


Previous ID	SR-15316
Radar	rdar://58875480
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	maldahleh (JIRA)
Priority	Medium

md5: 1e9985f00dbb5c1b1959ca90b9b4237a

Issue Description:

[SR-15317] [Swift-DocC] Emit a warning for a "See Also" task group within a Topics section.


Previous ID	SR-15317
Radar	rdar://60684559
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 963ca050244e96619e8c563b137ddc6e

Issue Description:

It's easy to accidentally write a "See Also" section as part of a Topics section (like the following) instead of as it's own second-level heading like DocC expects:

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

### See Also

- ``RelatedSymbol``

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

## See Also

- ``RelatedSymbol``

[SR-15410] Can't document extensions with DocC


Previous ID	SR-15410
Radar	rdar://63987302
Original Reporter	rnikander (JIRA User)
Type	Bug

Attachment: Download

Additional Detail from JIRA


Votes	11
Component/s	Swift-DocC
Labels	Bug
Assignee	@theMomax
Priority	Medium

md5: 0a7941d59b134a8d6fcab0d5853ef0b5

Issue Description:

I have a Swift package in which I define some extensions on matrix types like simd_float3x3. I tried to use DocC to create documentation for this package, but I can't get it to show the extensions.

Example of code in my module that I can't document:

extension simd_float3x3 {
    /// Format the matrix with a default style
    public func formatted() -> String { ... }

I guessed at some syntax in the markdown files. For example: ``simd_float3x3/formatted``. But I'm not familiar enough with DocC yet to have any suggestions on what the syntax should be.

[SR-15319] [Swift-DocC] Remove diagnostic for use of "topic://" links


Previous ID	SR-15319
Radar	rdar://71579947
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 760938bf92615d19d1cca70e88f88e58

Issue Description:

Swift-DocC used to allow <doc:> style links to be written as <topic:> links. We no longer support this old syntax and all warnings related to it should be removed.

[SR-15364] Add render JSON top-level property to indicate what trait its primary contents applies to


Previous ID	SR-15364
Radar	rdar://84501056
Original Reporter	@franklinsch
Type	Task

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Task
Assignee	None
Priority	Medium

md5: 017ead1e12e51b666ee76c8c1b27a939

Issue Description:

Per suggestion in https://forums.swift.org/t/extending-swift-docc-render-json-to-support-multi-language-symbols/52881/4, create a top-level property in render JSON that tracks what variant the primary render JSON contents apply to.

[SR-15317] [Swift-DocC] Emit a warning for a "See Also" task group within a Topics section.


Previous ID	SR-15317
Radar	rdar://60684559
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, DiagnosticsQol, StarterBug
Assignee	@Kyle-Ye
Priority	Medium

md5: 963ca050244e96619e8c563b137ddc6e

Issue Description:

It's easy to accidentally write a "See Also" section as part of a Topics section (like the following) instead of as it's own second-level heading like DocC expects:

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

### See Also

- ``RelatedSymbol``

# ``ModuleName/SymbolName``

Symbol overview.

## Topics

### First Task Group

- ``ChildSymbol``

## See Also

- ``RelatedSymbol``

[SR-15519] Suboptimal line breaking in declarations


Previous ID	SR-15519
Radar	None
Original Reporter	@karwa
Type	Bug

Attachment: Download

Environment

Swift-DocC main branch @ 24.11.21

Swift-DocC-render main branch @ 24.11.21

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: 8d8297585e37b14f35b6ba398350468e

Issue Description:

I'm finding that Swift-DocC's line breaking is sometimes a bit awkward. For example:

Line break in the middle of the name "BidirectionalCollection"

Line break in the middle of the name "StringProtocol"

Line break in the middle of the dictionary sugar's value type

Line break in the middle of a constraint.

—

This is obviously a very difficult problem - in the long-term, pie-in-the-sky ideal case, we'd have some kind of WebAssembly version of swift-format, using the compiler's syntax parser to dynamically and intelligently break the symbol based on its meaning and the available width.

In the mean time, it turns out that Swift-DocC is automatically inserting word-breaks, but does so at very strange positions. In the first example, there are HTML <wbr> tags between "String" and "Protocol" and between "Bidirectional" and "Collection". Removing those improves the situation a little, and BDC no longer breaks in the middle:

But it may be possible to improve this yet further, with better tuning of where we emit non-breaking spaces and explicit word breaks/zero-width spaces. For example, if I replace the spaces in the generic constraints list with non-breaking spaces, we get a much nicer result:

As for what these rules could look like, I would suggest the following as a starting point, although they'll likely need some experimentation and tweaking:

A function's name, generic parameter list, and opening bracket of the parameter list, should all be considered a single unit, with a word-break/ZWSP after the opening bracket.
"label name: Type" elements in a function's parameter list should internally use non-breaking spaces, and be separated from each-other by breaking spaces; we'd prefer breaks before/after each parameter than in the middle of one.
A function's parameter list's closing bracket, effects (throws, async) and return type should likewise be considered a single unit, with a word-break/ZWSP before the parameter list's closing bracket and after the return type and non-breaking spaces within that region.
Word-break between a function's return type and where clause
"GenericType : MyProto" elements in a function's where clause should be considered a single unit for text flow and internally use non-breaking spaces, just like function parameters.

Applying these to the 3rd example, it looks much better, and more readable. It still not absolutely perfect - I'd love for the closing bracket to reset the indentation, but I can't think of a way to express that with Unicode line breaks. Perhaps that's something where Swift-DocC-render could add some heuristics if it thinks the parameter list is likely to need line breaks, so it can try to keep that section isolated to set of lines with the fewest internal line breaks.

[SR-15321] [Swift-DocC] Android support for DocC in the toolchain


Previous ID	SR-15321
Radar	rdar://81975323
Original Reporter	@ethan-kusters
Type	Bug

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: 4c80bba26b38c2f631b41e75f31347b9

Issue Description:

Set specific build flags for building Swift-DocC in the toolchain for the Android platform. There is an example of this in the swift-driver repository: https://github.com/apple/swift-driver/blob/main/Utilities/build-script-helper.py#L103.

[SR-15585] Invalid task group list items do not have source locations


Previous ID	SR-15585
Radar	rdar://problem/89641499
Original Reporter	@karwa
Type	Bug

Environment

Swift-DocC 92f7fe1

Also present in the Xcode 13.1 build

macOS 11.6

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: 9c2a4789ba12c4f99e093155320236fb

Issue Description:

If there is a non-link item in a "See Also" list or Topics list in a Swift source file, DocC will emit a warning: "Only links are allowed in task group list items" without a source location.

This makes locating the cause of the warning incredibly difficult. The only way I was able to discover where these things were coming from is by building my own version of DocC with a bunch of "dump()" calls thrown around.

This revealed that DocumentCurator was unable to find a document location for the node reference here:

swift-docc/Sources/SwiftDocC/Infrastructure/DocumentationCurator.swift

Line 176 in d94139a

diagnostic.source = context.documentLocationMap[nodeReference]

Steps to reproduce:

Add an item to a "See Also" list or "Topics" list which is just plain text (not a link), and build documentation. DocC will emit a warning with no location.

/// A thing
///
/// ## Topics
///
/// ### Things about Things
///
/// - bar
///
struct Foo {
}

[SR-15685] "Inherits from" relationship field appears blank when subclassing a class from another module


Previous ID	SR-15685
Radar	rdar://80090675
Original Reporter	@ethan-kusters
Type	Bug
Status	Resolved
Resolution	Done

Attachment: Download

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug, StarterBug
Assignee	dgrumberg (JIRA)
Priority	Medium

md5: 017fab3f29d8a315c4481d90fb1ec6c1

Issue Description:

Summary:
When I subclass a class defined in another module, the “Inherits from” relationship field is listed on the page but its blank.

The `targetFallback` does appear in the symbol graph like it does for protocol conformance, so this appears to be a DocC bug, not a symbol graph bug.

I'd expect the behavior for subclassing here to match the behavior for protocol conformance.

"relationships": [
    {
        "kind": "conformsTo",
        "source": "s:3Foo0A5ClassC",
        "target": "s:3Bar0A8ProtocolP",
        "targetFallback": "Bar.BarProtocol"
    },
    {
        "kind": "inheritsFrom",
        "source": "s:3Foo0A5ClassC",
        "target": "s:3Bar0A5ClassC",
        "targetFallback": "Bar.BarClass"
    }
]

Notes:
Attaching the full symbol graph for this project along with a reproducing Swift package.

[SR-15353] Swift-DocC flaky test: CollectionConcurrentPerformTests.testSerialConcurrentPerform


Previous ID	SR-15353
Radar	rdar://84374211
Original Reporter	@franklinsch
Type	Bug
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	@QuietMisdreavus
Priority	Medium

md5: ea9eb609ca1f6a58dc5503eecf6d43d7

Issue Description:

CollectionConcurrentPerformTests.testSerialConcurrentPerform is flaky on Swift CI Linux (Ubuntu 16.04). For example, the test passed in #1 but not in #2 and #11

[SR-15354] Update Render JSON spec with for new variant overrides property


Previous ID	SR-15354
Radar	rdar://83667105
Original Reporter	@franklinsch
Type	Task
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Task
Assignee	@franklinsch
Priority	Medium

md5: 46191424b60dc298cba237a4185e737f

Issue Description:

Update the render JSON schema with the changes introduced by #11

[SR-15839] Add external media support for DocC documentation


Previous ID	SR-15839
Radar	None
Original Reporter	@Kyle-Ye
Type	New Feature
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	New Feature
Assignee	@Kyle-Ye
Priority	Medium

md5: 59c5fa9b08c41026ac4e9bbfb6b64eab

Issue Description:

Forums discussion here: https://forums.swift.org/t/can-we-link-and-render-external-images-that-is-from-urls/55098/6

[SR-15385] [Swift-DocC] Enable parallel documentation builds on Linux and Android


Previous ID	SR-15385
Radar	rdar://problem/84827531
Original Reporter	@ethan-kusters
Type	Bug

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Bug
Assignee	None
Priority	Medium

md5: 41694a5883ad32bd579158072fa4543b

Issue Description:

Documentation conversion is currently run serially on non-macOS systems but in parallel on macOS. The parallel workflow was disabled on Linux because of unusually high memory usage when converting large documentation catalogs in parallel. This issue should be investigated and, if there is a memory leak, resolved so that documentation conversion can be parallelized on non-macOS systems.

[SR-15572] [Swift-DocC] Support custom display names for frameworks


Previous ID	SR-15572
Radar	rdar://problem/86279414
Original Reporter	@ethan-kusters
Type	Improvement
Status	Resolved
Resolution	Done

Additional Detail from JIRA


Votes	0
Component/s	Swift-DocC
Labels	Improvement
Assignee	@d-ronnqvist
Priority	Medium

md5: c3fa5665e09635e8743f8f59ebc6b0c8

Issue Description:

Today Swift-DocC always renders a framework's more technical name as the title of the framework overview page. In many scenarios, developer's will likely want to customize this value when they're not limited by what characters are valid in the framework's actual name.

For example, the SwiftDocC framework, may prefer to render as "Swift DocC" or "Swift-DocC". Or maybe "ArgumentParser" would prefer to render as "Swift Argument Parser".

Swift-DocC should expose customization on the CLI and in documentation catalogs for a module's display name.

apple / swift-docc Goto Github PK

swift-docc's Introduction

Swift-DocC

Getting Started with DocC

Writing and Publishing Documentation with Swift-DocC

Versioning

Bug Reports and Feature Requests

Submitting a Bug Report

Submitting a Feature Request

Contributing to Swift-DocC

swift-docc's People

Contributors

Stargazers

Watchers

Forkers

swift-docc's Issues

Summary

Recommend Projects

Recommend Topics

Recommend Org

Jobs