Implement an asset pipeline for CSS, JavaScript, and images about swift-doc HOT 11 CLOSED

So from what I gathered so far, here's what we want to achieve:

1. Track the CSS (or other pre/post processor) sources in the repository.
2. Generate the CSS resources before or during build time (lint, minify, etc).
3. Since we can't load these at runtime (SPM limitation), we have to inject them during build time.

For 1, can we consider using Sass or PostCSS for taking care of things like auto-prefixing, polyfills, etc?

For 2, I guess webpack is a good place to start. Not my favorite in terms of overhead, but we can try to keep the config manageable.

For 3, I guess auto-generating the Swift file is one option. Any others that we can consider?

from swift-doc.

@kaishin Done. Have fun!

from swift-doc.

The same pipeline can be used to take our icons and inline them into our CSS

from swift-doc.

@mattt This is the issue we discussed earlier, right?

from swift-doc.

@kaishin Indeed it is. Any thoughts / opinions?

from swift-doc.

Oh and we have also to decide how running webpack commands will fit in the workflow. Doing it manually is likely going to be error-prone.

from swift-doc.

Oh and we have also to decide how running webpack commands will fit in the workflow. Doing it manually is likely going to be error-prone.

Here are a few options to consider:

Option A: Add a call to webpack in our Makefile before we run swift build; this would guarantee consist results with derivative asset files, but would introduce npm as a hard dependency for (manual / non-bottled) installation.

Option B: Add webpack to a git pre-commit hook; this has the benefits of A without making npm a hard dependency (you only need it as a contributor, not a user). However, git hooks are inconvenient to setup.

Option C: Accept the possibility of stale assets in builds.

Right now, I'm towards Option C.

If you're working on the design of the HTML docs, you're almost certainly running webpack every time you make a change to see the result (perhaps automatically with a Guardfile or the like). When you're done working, and it comes time to commit the changes, any derivative files would be already generated — fresh and ready to go.

The one situation where this would fail, though, is with conflict resolution. If I merge a PR that changes a source asset, I may need to re-run webpack to refresh the results. I think it'd be possible to write a GitHub Action to do this automatically, but I'd defer that work until it's proven to be necessary.

from swift-doc.

So from what I gathered so far, here's what we want to achieve:

1. Track the CSS (or other pre/post processor) sources in the repository.
2. Generate the CSS resources before or during built time (lint, minify, etc).
3. Since we can't load these at runtime (SPM limitation), we have to inject them during build time.

For 1, can we consider using Sass or PostCSS for taking care of things like auto-prefixing, polyfills, etc?

Absolutely. I have a slight preference for PostCSS if it's convenient, but Sass is fine too.

For 2, I guess webpack is a good place to start. Not my favorite in terms of overhead, but we can try to keep the config manageable.

Actually, taking another look at the available options, I think Parcel looks a bit more palatable, at least for an MVP.

For 3, I guess auto-generating the Swift file is one option. Any others that we can consider?

Alternatively, we can just copy the files into the built documentation directory, and have our HTML point to where they'll be. Inlining CSS was something I did primarily to get beta 1 out the door.

from swift-doc.

Absolutely. I have a slight preference for PostCSS if it's convenient, but Sass is fine too.

Cool, I can set that up. It's my preference too.

Actually, taking another look at the available options, I think Parcel looks a bit more palatable, at least for an MVP.

Let's go with Parcel for now. I looked at it a while back and it seemed nicer.

Alternatively, we can just copy the files into the built documentation directory, and have our HTML point to where they'll be. Inlining CSS was something I did primarily to get beta 1 out the door.

I prefer this option as well. Keeps things tidy at a negligible cost.

Right now, I'm towards Option C.

C it is. I was going to pitch A initially but you bring up good points about the hard npm dependency.

from swift-doc.

@mattt Can you assign me to this issue? Not able to do that myself...

from swift-doc.

@mattt Let's continue the discussion on the PR draft directly :)

from swift-doc.