Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add netlify continuous deployment section #1217

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Conversation

apreshill
Copy link
Contributor

This PR adds a section on Netlify continuous deployment, right after a section on Netlify Drop, to the publishing chapter of the book.

@apreshill apreshill added book About the bookdown book contains in inst/examples documentation labels Jul 28, 2021
@apreshill apreshill requested review from yihui and cderv July 28, 2021 23:56
Copy link
Collaborator

@cderv cderv left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few comments below because I don't understand some stuff.

Also, I wonder if it would be better to have a Netlify chapter, then two subchapter , one one Drop and one on deployement

6. Publishing
    |>> RStudio Connect
    |>> Netlify
        | >> Netlify Drop
        | >> Netlify Deployment 
    |>> Github
        |>> Github Pages
        |>> Using Github Actions

I understand you do that to offer option from simpler to more advanced, right ?

Maybe the publishing section needs further restructuring later on to organize by type of method or other instead of services. 🤔

Comment on lines +96 to +98
Continuous deployment means that when you push your code to a Git(Hub) repository, Netlify detects this push, then automatically publishes the updated site for you- no manual steps are needed after the initial setup. As described in the Netlify documentation (https://www.netlify.com/docs/continuous-deployment/):

> "Continuous deployment works by connecting a Git repository to a Netlify site and keeping the two in sync."
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This approach suppose that the built book is commited to Github in the main branch right ?

Source repo needs to have

  • Source of the book to be able to rebuild the book
  • Source of the website (build book) so that Netlify can retrieve and deploy (bc Netlify does not know how to build the book unlike with Blogdown and Hugo)

I am not sure this is clear to every user. This methods and Github Pages / Gitlab Pages without CI are the same.

Maybe we should mention such things ?

Comment on lines +136 to +137
* Switch your output directory back to `_book` (the default). In your `_bookdown.yml` file, you can either comment out that line (`#`) or delete it.
* If you want a different output directory, replace all future instances of `_book` with your output directory.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why this is needed ?

Netlify lets you pick the folder in which the files for the static website are stored in git right ?

So any output_dir value would work, wouldn't it ?

Comment on lines +139 to +144
* Clean up committed files. If you placed a directory like `docs` in your GitHub repo, you need to do an extra step in the terminal to remove it with:<br>
```bash
git rm -r --cache docs/
git commit -m 'Remove the docs folder'
git push origin master
```
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need this for Netlify deployment exactly ?

These commands are to remove a folder from being tracked by Git without removing the folder. Usually when you want to untrack something and add it to gitignore.

Suggested change
* Clean up committed files. If you placed a directory like `docs` in your GitHub repo, you need to do an extra step in the terminal to remove it with:<br>
```bash
git rm -r --cache docs/
git commit -m 'Remove the docs folder'
git push origin master
```
* Clean up committed files. If you placed a directory like `docs` in your GitHub repo, you need to do an extra step in the terminal to remove it with:<br>
```bash
# Tells git to stop tracking the docx/ folder but does not delete this folder
git rm -r --cache docs/
git commit -m 'Remove the docs folder'
git push origin master

Also maybe you should keep using `main` instead of `master` for examples also ? 

@apreshill
Copy link
Contributor Author

Re: the organization. What you propose was how I did have it, but then the subsections end up heavily nested. And folks who use Netlify won't find the GitHub Actions section. What I would do:

6. Publishing
    |>> RStudio Connect
    |>> Netlify Drop (no CI)
    |>> Netlify Continuous Deployment (no CI)
    |>> Github Pages (no CI, to `docs/`) _[this and the above section could be fused- maybe?]_
    |>> Continuous integration (Github Actions to deploy to branch, maybe leave off Travis)
           |>> show both Netlify + GH Pages 

@cderv
Copy link
Collaborator

cderv commented Jul 29, 2021

Yes I agree I think this makes sense. I would add rstudio connect on the CI part because this is what we use for our books and it is working quite well. (However, it requires maybe some simplification - needs to find time to document and update publish_book() function)

Copy link
Member

@yihui yihui left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like #1218 (review), I feel both the documentation and usage will become easier after we provide an action or a function publish_netlify(). Users would only need to provide a site id and personal access token, and we can take care of the rest of technical details.

@apreshill
Copy link
Contributor Author

I would LOVE to document that ;)

Base automatically changed from docs/netlify-drop to main August 9, 2021 19:31
@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
book About the bookdown book contains in inst/examples documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants