Refactoring deploy

[oscarlevin]

For version 2.0.0, I wonder if we should rethink how the deploy function works. Previously, you deployed just a target (and pretext deploy just assumed you meant the first target, usually web). Then we added the option to deploy multiple targets at once and also deploy the contents of site, a folder in the root of your project that might contain a landing page.

The current way we decide between these two options is by looking at project.ptx and seeing if any targets had a deploy-dir element (legacy) or site attribute (v2). This seems sneaky to me.

Further complicating things is that soon we will want pretext deploy runestone to do something different (for the target whose name is runestone). Perhaps we would want to deploy multiple single targets to different places? Probably best not to try to go down that path. I assume that we would never want to deploy a runestone target to github pages, right?

Here is my proposal, that I would appreciate feedback on:

• pretext deploy has two possible arguments, gh-pages (default) and runestone.
• For the gh-pages deploy, we always deploy a site directory, possibly creating it if it doesn't exist or isn't specified in the manifest.
  • If no targets have a site attribute, we assume the first html target. That gets copied to to root of the site folder. So this is really just the same behavior as now.
  • If some targets have a site attribute, we deploy them as requested (also possibly creating the site folder and a basic landing page. Eventually.
• The runestone deploy can come later, as we decide on workflow as discussed elsewhere (Make deploying to Runestone easy #513).

Essentially, this is just changing what the argument means on the deploy command. I think it will also simplify the code since we don't need to do as much guessing.

Thoughts?

[bjones1]

I'd suggest runestone deploy [target-name]. If the target-name is missing, pick either the first target with a site or, failing that, the first web target. If the target-name is provided, then deploy that target.

[oscarlevin]

But then how do you deploy multiple targets to gh-pages? The idea of a site folder is to have a landing page and support hosting an html build, as well as a pdf, say.

[bjones1]

Good point! I didn't realize this piece. I like your original proposal, now that I understand this better. Perhaps there's also an option all, which is the equivalent of gh-pages and runestone? (The idea is: provide an easy to to deploy everything.)

[oscarlevin]

I've been thinking about how we should "stage" a deployment that includes a "site" (landing page). Options:

1. Add a deploy_preview folder inside the project, ignored by .gitignore and copy all outputs and contents (or conversion) of the site folder. I don't love that we are getting another folder of generated things though, as that is confusing to me and I assume other authors.
2. Do the same thing, but use the output folder for this purpose. The problem here is that there might be more things in output than what would be deployed.
3. Do the same thing, but in a temporary folder. So we basically do a dry-run on deploy (with the command pretext deploy --preview) and view the temp directory just as it would be used when pushing to gh-pages.

I'm leaning toward 3. It has the advantage of not tempting users to mess with deploy files between building the site and deploying it. And for users who do not use the site directory, they never need to worry about the difference between site, output, and deploy-preview.

[StevenClontz]

I had begun work at #556 while Oscar wrote the last post.

We went with option 1, but by default it lives in output/stage, so it's tucked away with the other files folks shouldn't be editing directly (but may want to view).