Avoid horizontal scrolling in formatted code

[MaxDesiatov]

Currently, formatted code in swift-doc requires horizontal scrolling in a lot of places. See attached screenshot from ComposableArchitecture package docs.

It would be great if swift-doc could reformat the code to some narrow width, at least appropriate for the default font. Something like SwiftFormat could help with this, as it gained line width reformatting capabilities recently.

[mattt]

It would be great if swift-doc could reformat the code to some narrow width, at least appropriate for the default font. Something like SwiftFormat could help with this, as it gained line width reformatting capabilities recently.

A few months back, I had an experimental branch that used SwiftFormat swift-format, but dropped it due to difficulties coordinating the shared libSwiftSyntax dependency and inflexibility of the API. It looks like things may have improved recently, so I'd like to revisit that again soon.

[MaxDesiatov]

The great thing about nicklockwood/SwiftFormat is that it doesn't have any dependencies on Swift Syntax, so it shouldn't conflict in any way in that sense.

[mattt]

Alright, so I got as far as wiring up swift-format into swift-doc before realizing that what we actually want is to preserve whatever formatting there was in the original source. If folks want things to look different in the docs, they can run swift-format / SwiftFormat / what have you as a preprocessing step first; no reason to put that on `swift-doc itself.

Doing that requires some changes to how we're processing source code (right now, those declarations are actually generated from the description of SwiftSemantics types). We'd also probably want to tweak the CSS to make sure we're accommodating a reasonable column size (68, 80, or 100, perhaps).

[MaxDesiatov]

actually want is to preserve whatever formatting there was in the original source.

I'm not sure that would be ideal. The default font in swift-doc-rendered pages is bigger than the default font of most editors and terminals, so even 80 characters may not be narrow enough to avoid horizontal scrolling. And then the only way to fix that is to submit PRs to change formatting of other people, and that's one of the most opinionated things out there.

[mattt]

Random idea: What if we did something like minimumScaleFactor / adjustsFontSizeToFitWidth and assigned a class / data attribute to each declaration depending on the width, which the CSS could use to size text?

In the provided example, the IfLetStore declaration is just around 80, so we'd adjust the font size down for that 68 – 80 column bucket. A slightly longer declaration could be even smaller. And beyond a certain point, we give up and overflow scroll.

Do you think that's a reasonable approach?

[MaxDesiatov]

I'm not quite sure. To me right now it sounds almost as complicated as integrating SwiftFormat, but maybe I misunderstand the technical details of the approach.

[mattt]

@MaxDesiatov I eventually found a simpler solution that involves minimal CSS changes. See #204.