Experimental markdown output

[jrturton]

Issue #1301

Summary

This PR addresses the changes proposed in #1301. It involves a new translator / semantic visitor / markup walker to create the new outputs from DocumentationNode. This is done for each node, after the render JSON is generated.

Dependencies

None

Testing

There are extensive unit tests in MarkdownOutputTests.swift. Testers can also run the convert command against any catalog with the --enable-experimental-markdown-output and --enable-experimental-markdown-output-manifest flags set.

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
• Updated documentation if necessary

[d-ronnqvist]

There's a lot to unpack here and I've only had the time to skim thought the code but these are a few things that stand out to me:

• If this is intended as experimental feature, then it can't add actual public API because consumers of SwiftDocC would have no way of knowing what API is stable and what is experimental and could still have breaking changes or be removed.

  If a goal of this API is that clients can use it while it's still experimental then it needs to be marked as SPI (using @_spi(SomeName) so that those clients make a deliberate decision to use it and acknowledge that it may have breaking changes.

• The added tests follow a pattern not seen elsewhere in the repo. I left some more specific comments about that.

[d-ronnqvist]

If it's a goal of this code that clients can use it without depending on SwiftDocC, should it be moved to its own target that consumers can depend on instead?

[d-ronnqvist]

Are these methods that only print meant to be included? Is there more work coming that would add support for these page elements?

[d-ronnqvist]

This isn't a pattern that any other test is doing. It's also relies very heavily on opaque test content in different files which makes the tests harder to read and debug if something changes.

[d-ronnqvist]

There are two things about this that we try to avoid in new tests:

• It relies on opaque, on disk, test fixtures but only verifies a small portion of it (a single file)
  There are two reasons why we try to avoid this:
  • People can't tell what the test is doing from looking at it. In this example, I don't know why that specific markdown content is expected without looking at content of the Links.md article in the test fixtures.
  • Because multiple different validations use the same test fixture, the loaded context for each test contains more pages than necessary. This makes it harder for people to put breakpoints and debug the test if something changes in the future because they need to step through a processing of data that's not being verified in this test.
• Multiple tests load the same content to perform a single verification. This isn't a pattern that other tests are doing. In this file, the repeated disk activity has been mitigated by using unstructured concurrency in a way that's another pattern not seen in other tests.

Instead, the best practice for tests like this would be to define a the minimal amount of input for each tests, directly with the test, and perform all related verifications in the same test.

---

For example, after reading these test, then going to the Article.md, I can conclude that this is verifying the format of a link to a symbol and a link to an article, both in prose and in a topic section.

The way I would write this is something along the lines of:

let catalog = Folder(name: "Something.docc", content: [
    TextFile(name: "First.md", utf8Content: """
    # First Article
    
    This article links to a symbol and another article in prose and in a topic section
    
    ``SomeClassName`` and <doc:Second>
        
    ## Topics
    - ``SomeClassName`` 
    - <doc:Second>
    """),
    
    JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: [
        makeSymbol(id: "some-symbol-id", kind: .class, pathComponents: ["SomeClassName"])
    ])),
    
    TextFile(name: "Second.md", utf8Content: """
    # Second Article
    
    This empty article is only being linked to.
    """),
]))

let (_, context) = try await loadBundle(catalog: catalog)
XCTAssert(context.problems.isEmpty, "Unexpected problems: \(context.problems.map(\.diagnostic.summary))")
let markdownOutput = // ...

then, you could either do the 4 contains(...) checks that relate to this test input or you could do an XCTAssertEqual(...) over the entire markdown output which should be about as short as the "First.md" article input.

The main benefits with this style of testing:

• All the inputs are right there in the test. You can see that the test is about an article linking to a symbol and an article.
• The test inputs can act as documentation about the test by describing the purpose of inputs in file abstract (instead of lorem ipsum text or other placeholder content)
• Because the test inputs only contains two articles and a symbol, there's a minimal amount of pages being processed which makes it easier to perform debugging actions like, dumping the entire link hierarchy, dumping the topic graph, printing all known page identifiers, etc.
• The test uses its own in-memory file system, so it doesn't need to read from disk.

[d-ronnqvist]

To the previous point about debugging tests. I can't tell from this file how many symbols there are or what the purpose of each symbol are. I can't tell if there's a wide range of symbols that covers any edge cases or if it's mostly structs, classes, methods, and properties.

[d-ronnqvist]

FYI: You have your file:///Users/richard/Documents/... path components in this file.

If there's some symbol graph data that's really complex and hard to recreate, so that we opt to use an exported file for it, we rename that to file:///Users/username/path/to/...