Clarify GitHub Pages instructions for the publish action

[waldyrious]

The instructions for GitHub Pages had both missing details, and duplicated information. I did the following changes:

• Added a first step to create the gh-pages branch in the GitHub UI. All the other steps are performed in the web UI, so there's no apparent reason for this one to be done via the command line.
• Described the activation of GitHub Pages in a bit more detail (I suspect this is actually not necessary — IIUC the action does enable GitHub Pages automatically. But I think it's better to leave this step explicitly described, so the process doesn't deviate too much from the usual GitHub Pages setup.
• Moved the step to create the action (workflow) file to after these two preliminary steps, and expand the instructions on how to use the example .yml file.
• Removed steps 4 and 5, since they are subsumed by the instructions already in the examples/quarto-publish-example.yml file (also, the link in step 5 was empty so it didn't actually work)

This is my first time trying out Quarto, so I'm happy to take on any suggestions to improve my changes in case I missed anything!

[cscheid]

Thanks, but we really do want to be careful and not ask users to take extra steps when they're not needed.

The publish action should be creating gh-pages branches automatically when needed (because quarto publish does so).

But I think it's better to leave this step explicitly described, so the process doesn't deviate too much from the usual GitHub Pages setup.

If you allow me to be frank, that's a bad change; we want to describe the steps as they are needed for Quarto users. This PR makes that situation worse.

[waldyrious]

I understand your perspective, @cscheid, and I'd be happy to replace the step with the creation of the branch on GitHub UI with running quarto publish gh-pages locally. If I do so, would you consider the other changes in this PR?

[cderv]

I believe if we need to clarify a documentation on how to publish this would be in our main doc. We document all this in https://quarto.org/docs/publishing/github-pages.html#publish-command

Is this doc not enough ?

I was to do an improvement, it would be point to the doc from the README.

[waldyrious]

I was to do an improvement, it would be point to the doc from the README.

I see, and understand the appeal of that approach (avoiding the need to maintain two sources of information, ensuring they're in sync and both up to date, etc.). However, the level of detail between the README and the docs site is quite different, and I believe they may both be useful to different kinds of audiences.

In my case, for example, as someone who had never used Quarto and was just trying to figure out the minimal set of steps to enable GitHub Actions-based publishing of a Quarto site from a repository I had forked (so I could test changes before submitting them as a PR to the upstream repository), the README was the perfect level of detail, and if I had only the docs site to go with, I suspect I'd have given up, given the sheer amount of information shown there, and lack of a step-by-step, "quickstart"-type document as what the README provides.

In any case, I'll grant that I did manage to get things working with the README as it currently is, so keeping things as they are would not be too bad IMHO; still, I wished that this PR could help iron out the friction points I encountered while following the instructions from the README, so as to make things easier for other people in similar situations.

[cderv]

lack of a step-by-step, "quickstart"-type document as what the README provides.

I am surprised by this feedback. Our documentation on publishing shows steps to follow with even some screenshots and code blocks.

• Setting up the source branch deployment in the repo https://quarto.org/docs/publishing/github-pages.html#source-branch
• Configuring .gitignore for not commiting the output https://quarto.org/docs/publishing/github-pages.html#ignoring-output
• Publishing using Github Actions : https://quarto.org/docs/publishing/github-pages.html#github-action
  • Even explaining to opt in freeze to not require computation in GHA
  • And what to do and use for the workflow https://quarto.org/docs/publishing/github-pages.html#publish-action
  • With others example when computation are needed : https://quarto.org/docs/publishing/github-pages.html#executing-code

How do you suggest we improve this doc ? Missing parts ? Another organization ?

In my case, for example, as someone who had never used Quarto and was just trying to figure out the minimal set of steps to enable GitHub Actions-based publishing of a Quarto site from a repository I had forked

My thinking was a first time quarto user would go first in the main Quarto documentation to know what to do, and that README in this repo was more of a quick access reminder for already Quarto user who wants to automate deploy.

Maybe this is not the case 🤔 Thanks for the feedback !

[waldyrious]

I'm sorry, I did not mean to diminish the care put into the docs, nor their usefulness. I probably failed to emphasize the main factors behind my statement: the "quick" in quickstart (or one might say concise, to use a different word) and "level of detail". Probably using "step-by-step" muddied the waters a bit.

Again, I was not looking at Quarto as a goal in itself, but as a step towards achieving my goal of previewing changes to someone else's site. I was not (yet) considering actually learning Quarto as a tool I'd want to use and eventually master myself. So something very short and that got the job done without much fanfare was the ideal on-ramp to allow me to accomplish my immediate goal — and incidentally, it would make me an unwitting user of Quarto, and a satisfied one at that given the frictionless experience, so probably would put me in the path of considering it for my own projects in the future.

All this to say that I don't really have suggestions for improving the docs — I think they look great and are probably well-suited to the intended audience. I would just encourage you guys to look at the README as not just a quick reminder for existing Quarto users, but also a possible low-barrier entry point for non-Quarto users (this is an approach that we use in the tldr-pages project — see e.g. guideline #2 in CONTRIBUTING.md).

In any case, I would venture that the suggestions I made in this PR do improve the README contents, regardless of its intended use: there was some redundancy, a broken link, etc. So even if you don't share my view that it may be useful for beginners, I think it's still worth fixing these issues.

[cderv]

Thanks a lot for the thoughtful feedbacks !

I understand, and we will rethink our Quarto Actions doc for better alignment and step-by-step guide between doc in this repo and the one in the website.

Thanks again for taking the time to explain everything. I very appreciate it !

[waldyrious]

I hope it helped :) And just to be sure: should I abandon this PR and delete the branch, or is there a chance you may consider marginal improvements to the current contents of the README along the lines of what I've proposed above, ahead of a later, possibly deeper restructuring?

[cderv]

Sorry, I did not linked to here. I already did some adaptation to the README, and fixed the link also.

See new README: https://github.com/quarto-dev/quarto-actions/tree/main/publish

Hope you'll find this clearer.

[waldyrious]

Oh! Indeed I had missed that. It is clearer, yeah! I do still think that steps 3 and 4 are redundant and potentially even confusing, because they're already included in step 2 (specifically, in the yaml snippet here). So repeating them in the README can lead one to wonder if they're there deliberately and attempt to figure out what may be different, when in fact it's the same thing.

Also, I would perhaps reword the instructions in step 2, since the two sub-items overlap and it's not exactly evident how. Allow me to rebase and update this PR with a suggestion, to make it explicit what I mean.

[waldyrious]

I've updated the PR branch — please check the diff. I actually ended up removing the mention of the quarto-publish-example.yml file altogether, since it merely repeats (with slightly different syntax) what the doc already says — especially considering the presence of the yaml snippet in the docs, which serves the same purpose.

The parts of the file that are not in the docs are additional template blocks for other publication platforms (which are irrelevant for the GitHub Pages scenario anyway), and the bit about dependencies, which is covered in the Executing code section — again, with code snippets using functionally identical syntax but just enough minute differences to make one wonder whether the discrepancy is intentional.

[waldyrious]

Oh, weird, apparently updating a PR's source branch does not update the PR if it's closed. Please check the diff here, then.

[cderv]

Thanks for the new feedback. I don't want to remove those part (otherwise I would have done it).

However, I understand what you trying to tell me. So I adapted again the README.

thank you !

[waldyrious]

Understood! Thanks for your patience and the improvements you made to the docs/README :)