search

Openscapes / quarto-website-tutorial

Example quarto site without R or Python
https://openscapes.github.io/quarto-website-tutorial
Creative Commons Attribution 4.0 International
49 stars 96 forks source link

Problems I had with tutorial (July 2023) #25

Closed eldobbins closed 8 months ago

eldobbins commented 1 year ago

Hi! Thank you so much for making this tutorial available for new users of Quarto. It was very helpful to have a defined project because I have never used GitHub Actions before. I wanted to let you know what issues I hit in case you would like to incorporate solutions in the documentation (or want me to submit a PR...)

  1. https://openscapes.github.io/quarto-website-tutorial/explore.html#setup-github-action describes make a new file quarto-publish.yml but that file is already in the repo. I didn't notice that, so got a cryptic GitHub error when I tried save a new file to that name.
  2. https://openscapes.github.io/quarto-website-tutorial/explore.html#fork-to-your-account suggests following the instructions at https://github.com/thefaylab/lab-manual/wiki/Quick-steps-to-making-a-copy-of-the-lab-manual-&-publishing-it for setting up the repo. It had instructions for adding a new repository secret called EMAIL but doesn't say why. That was a little confusing because of the next problem I had.
  3. My Quarto workflow would not run. I thought it was due to 2 (above) but in fact, my repository did not give read-write permission to workflows by default. The only had read-read so it could not write the new files. To fix that, I went to Settings > Actions > General > Workflow Permissions (below the fold at the bottom of the page) and clicked the radio button for Read and write permissions
  4. I reran the Render and Publish workflow manually a few times via the Actions tab. That might be mentioned as an option rather than editting files to trigger the Workflow.
  5. For some reason, Settings > Pages was using the master branch instead of gh-pages. The symptom of that was that my Pages link was showing the README file from the main branch rather than the generated files from Render and Publish. Switching the branch and running the pages build and deployment workflow fixed that.
  6. Finally, I was still getting the README showing on the link, even after I could see in the Action logs that the deployment had been successful using the correct branch and everything. That's when I noticed at https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site that there can be a delay of 10 minutes up to an hour. All I had to do was wait, and eventually the correct content appeared.

It might be worth adding a troubleshooting page in case other people get as mixed up as I did! But the best part was that I knew there were solutions because you have created and used the tutorial. Thanks again.

jules32 commented 1 year ago

Hi, thank you so much for this feedback! I'm so glad it's been useful and that you've found places to improve. We'll be able to work on this more next month (vacation and conference travel at the moment) and would be happy to collaborate with you on it; if you'd like to submit a PR that would be super and we can continue from there :). Thanks again for the issue, I really appreciate it!

stefaniebutland commented 1 year ago

Hi @eldobbins. I'm part of the Openscapes team. Thank you for opening this rich and helpful issue! I was testing and responding to #26 just now and realized that some answers are in your issue.

Do you still have the time and energy to submit a PR? Your issue lays things out very clearly and we would really appreciate that. If yes, please tag me as a reviewer. Happy to join you for a virtual screenshare if that helps. If not, I'm happy to make the updates.

Thank you!!

eldobbins commented 1 year ago

Hi;

I hope you can make the updates and that it isn’t extra trouble for you. I’ve gotten pulled to another project so it will take me a while to get back to this. I’ll get there eventually but it would be faster if you don’t wait for me. Liz

Sent from my iPhone

On Aug 18, 2023, at 10:26 AM, Stefanie Butland @.***> wrote:

 Hi @eldobbins. I'm part of the Openscapes team. Thank you for opening this rich and helpful issue! I was testing and responding to #26 just now and realized that some answers are in your issue.

Do you still have the time and energy to submit a PR? Your issue lays things out very clearly and we would really appreciate that. If yes, please tag me as a reviewer. Happy to join you for a virtual screenshare if that helps. If not, I'm happy to make the updates.

Thank you!!

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

stefaniebutland commented 1 year ago

I'm happy to make those updates soon Liz. Thank you again for giving such a thorough and helpful description!

stefaniebutland commented 10 months ago

Thanks to @amyfrey for reporting a couple more things we need to clarify

In the Quick steps to making a copy of the lab manual & publishing it tutorial, the first place where I run into a difference is step 3, setting the source branch to gh-pages. I do not have a gh-pages branch. I have tried creating one, as described in the quarto-website-tutorial, and then continuing with the faylab tutorial, but I still get the same issue, just the readme page is publishing.

Solution:

When I was forking I was copying the main branch only, and when I unselected that option and tried again the gh-pages branch was there, and now I can see the whole lab manual.

stefaniebutland commented 8 months ago

We've (finally) updated the tutorial and the issues you noted have been updated. Thank you again @eldobbins for being so thorough.