GitHub e RStudio

O RStudio é um popular ambiente de desenvolvimento integrado para R. Ele integra as ferramentas usadas com R em um único ambiente. O GitHub Pages permite que você hospede sites diretamente de seu repositório GitHub.

Neste tutorial, você aprenderá a:

Criar um novo repositório.
Trabalhar com seu repositório na máquina local usando o Git e o RStudio.
Usar o site github.com ou o GitHub Enterprise para concluir o fluxo de trabalho do GitHub.
Publicar e compartilhar seus documentos R Markdown usando o GitHub Pages.

Pré-requisitos

Para este tutorial é necessário ter uma conta no github.com ou GitHub Enterprise.
Se é novo no Git, GitHub e GitHub Pages, é recomendável preencher o GitHub Pages no campo da linha de comando primeiro..
Alguns conhecimentos de programação com R serão úteis, mas isso não é obrigatório.

Instalar o Git e o RStudio

Para este tutorial o Git e o RStudio serão usados para trabalhar com seu repositório GitHub.

Faça o download e instale o Git.
Faça o download e instale o RStudio. (1.1.383 ou superior).
Abra o RStudio.

Crie o repositório remoto no GitHub

Agora que tem o que precisa instalado localmente, vamos criar o repositório que irá conter seu novo site.

Em github.com, crie um novo repositório.

Observação: se sua organização usa o GitHub Enterprise, também é possível criar o repositório lá.

Dê ao seu repositório o nome carros. É possível usar um nome diferente.
Insira uma descrição para seu repositório.
Selecione visibilidade Public.
Selecione Initialize esse repositório com um README.
Clique em Add .ignore e selecione R.
Clique em Criar Repositório.

Clonar o repositório com RStudio

Depois de criar um repositório no GitHub (o repositório remoto), o próximo passo é cloná-lo em seu ambiente local.

No GitHub, navegue até a aba Code do repositório.
No lado direito da tela, clique em Clone or download.
Clique no ícone Copy to clipboard à direita do URL do repositório.
Abra o RStudio em seu ambiente local.
Clique em File, New Project, Version Control, Git.
Cole o URL do repositório e insira TAB para ir para o campo Project directory name.
Clique em Create Project.

Criar um documento R Markdown no RStudio

Agora que já tem uma cópia local do repositório, vamos adicionar um documento R Markdown ao seu projeto.

No RStudio clique em File, New File, R Markdown.
Selecione HTML output como saída padrão.
Clique em File, Save para salvar o documento.
Insira speed-and-distance e clique em Save.

Fazer commit e push das alterações para o GitHub

Depois de ter criado o documento R Markdown e terminado de realizar as alterações, é hora de fazer commit delas.

No RStudio, clique na aba Git no painel superior direito.
Clique em Commit.
Na visualização Review changes, marque a caixa preparada para todos os arquivos.
Adicione uma mensagem de efetuar commit, por exemplo Add initial speed and distance report.
Clique em Commit.
Clique no botão Pull para buscar quaisquer alterações remotas.
Clique no botão Push para enviar suas alterações para o repositório remoto.
No GitHub, navegue até a aba Code do repositório para ver as alterações.

Criar branches locais com Git

Vamos fazer mais algumas alterações em seu projeto usando os passos do GitHub Flow. Como o RStudio atualmente não suporta muito bem branches locais, iremos usar o Git na linha de comando do RStudio.

No RStudio, clique na aba Terminal no painel inferior esquerdo. A aba Terminal fica ao lado da aba Console.

Observação: se não conseguir encontrar a aba Terminal, verifique se está usando a versão 1.1.383 ou superior do RStudio. Clique em Help, About RStudio para verificar a versão atual.

Criar um novo branch. Substitua <BRANCH-NAME> por um nome descritivo, por exemplo speed-and-distance-report:
```
git branch <BRANCH-NAME>
```
Verifique o status de seu repositório:
```
git status
```
Observe que, embora você tenha criado um novo branch, ainda está em check-out para master, conforme indicado pela resposta em linha do Git.
Check out seu novo branch:
```
git checkout <BRANCH-NAME>
```
Verifique se o check-out em seu novo branch já foi feito:
```
git status
```

Fazer alterações locais com Git

Vamos gerar a HTML output em um diretório separado chamado docs. Para isso, adicionamos uma função no cabeçalho do documento R Markdown para 'knit' a output no diretório de saída desejado.

No RStudio, abra speed-and-distance.Rmd e adicione as seguintes linhas no cabeçalho sob o campo title:

 knit: (function(input_file, encoding) {
    out_dir <- 'docs';
    rmarkdown::render(input_file,
      encoding=encoding,
      output_file=file.path(dirname(input_file), out_dir, 'index.html'))})

Clique em File, Save para salvar as alterações.
Clique em Knit no painel de documentos para speed-and-distance.Rmd.

Fazer commit das alterações locais com Git

Depois de criar a HTML output, é hora de fazer commit das alterações.

Determine o status do seu arquivo. Lembre-se de que git status nos permite ver o status dos arquivos em nosso branch a qualquer momento. Seu arquivo está listado sob o título Untracked files:
```
git status
```
Adicione seu arquivo à área de preparação para que ele esteja pronto para se tornar parte do próximo commit:
```
git add .
```
Veja o status atual do seu arquivo. Seu arquivo agora está listado sob o título Changes to be committed. Isso nos diz que o arquivo está na área de preparação. Indica também que é um novo arquivo:
```
git status
```
Faça commit do arquivo. Substitua <COMMIT-MESSAGE> por uma mensagem de log descrevendo as alterações, por exemplo Knit output to a docs folder. Um commit diz ao Git para coletar todos os arquivos na área de preparação e armazená-los no controle de versão como uma única unidade de trabalho:
```
git commit -m "<COMMIT-MESSAGE>"
```
Veja o histórico de commits:
```
git log --oneline
```
Veja as alterações entre o branch master e o branch atual (HEAD):
```
git diff --stat --summary master..<BRANCH-NAME>
```

Abrir uma pull request no GitHub

Agora que já fez alguns commits locais, é hora de enviar suas alterações para a cópia remota do seu repositório no GitHub e criar uma Pull Request.

Efetue o push das alterações para o repositório remoto:
```
git push -u origin <BRANCH-NAME>
```
Crie uma Pull Request no GitHub.
Preencha o corpo da pull request com informações sobre as alterações que estão sendo introduzidas.

Fazer o merge de sua pull request no GitHub

Como esse é o seu repositório, você provavelmente não tem ninguém com quem colaborar (ainda). Siga em frente e faça o merge de sua pull request agora.

No GitHub, navegue até o Pull Request que você acabou de abrir.
Role para baixo e clique no grande botão verde Merge Pull Request.
Clique em Confirm Merge.
Exclua o branch <BRANCH-NAME>.

Criar o site de páginas

Este tutorial usará o GitHub Pages para publicar a HTML output. Para inicializar o GitHub Pages, precisamos realizar mais alguns passos:

No seu repositório, clique na aba Settings.
Role para baixo até a seção GitHub Pages.
Em Source, selecione master branch /docs folder.
Clique em Save para salvar as alterações.
Clique no URL gerado do GitHub Pages para visualizar o documento R Markdown renderizado.

Observação: Os sites do GitHub Pages são sempre públicos quando hospedados em github.com. Se quiser compartilhar um site com um número selecionado de pessoas, você pode usar o Jekyll Auth. No GitHub Enterprise, os usuários precisam se autenticar para acessar os sites do GitHub Pages quando o modo privado está habilitado.

Atualizar o repositório local

Depois de fazer o merge de sua Pull Request, será preciso atualizar sua cópia local do repositório.

No painel RStudio Terminal, digite:
```
git checkout master
```
Digite:
```
git pull
```
Exclua o branch local :
```
git branch -D <BRANCH-NAME>
```
Visualize o histórico de seus commits em um gráfico:
```
git log --oneline --graph --all
```

Também é possível visualizar o histórico de seus commits no RStudio. Clique em Commit no painel Git para abrir o painel Review Changes e clique em History.

Adicionar página de boas-vindas, tema e navegação

Vamos adicionar uma página de boas-vindas, tema e navegação para permitir a publicação de uma coleção de documentos R Markdown.

Primeiro crie um novo branch. Outra vez, substitua <BRANCH-NAME> por um nome descritivo, por exemplo add-theme-and-navbar:
```
git checkout -b <BRANCH-NAME>
```
Adicione um arquivo _site.yml com o seguinte conteúdo:

 name: "cars"
 output_dir: "docs"
 navbar:
 title: "Cars"
 left:
 - text: "Home"
 href: index.html
 - text: "Speed and Distance"
 href: speed-and-distance.html
 output:
 html_document:
 theme: cosmo

Adicione um novo documento R Markdown index.Rmd. Essa é sua página de boas-vindas.
Abra speed-and-distance.Rmd e remova os campos knit e output do título. O título agora ficará assim:

 ---
 title: "Speed and Distance"
 ---

Salve as alterações.
Abra o Console no painel inferior esquerdo e renderize o site usando o seguinte comando:

rmarkdown::render_site()

Confirme as alterações locais com Git:

 git status
 git add .
 git commit -m "Add home page, navigation and theme"

Abra uma pull request

Agora que adicionou a página inicial e a navegação, é hora de enviar suas alterações para a cópia remota do seu repositório no GitHub e abrir uma nova pull request.

Efetue o push das alterações para o repositório remoto:
```
git push -u origin <BRANCH-NAME>
```
Abra uma Pull Request no GitHub.
Vá em frente e faça o merge de sua Pull Request.
Veja seu site atualizado. O site deve ser semelhante a esta imagem.
Adicione o URL do GitHub Pages à descrição do repositório para que seja fácil encontrá-lo.

Se não conseguir se lembrar do URL do GitHub Pages, é possível acessar o URL na seção GitHub Pages na página de configurações.

Parabéns! 🎉

Você concluiu o fluxo de trabalho do GitHub com RStudio e adicionou um site do GitHub Pages ao seu projeto para publicar seus documentos R Markdown renderizados.

Links

O artigo R Markdown Websites no site R Markdown é um bom recurso para construir sites do GitHub Pages que hospedam coleções de documentos R Markdown.
Use o GitHub Desktop se preferir usar uma interface gráfica de usuário em vez de digitar comandos Git no terminal ao trabalhar com branches no RStudio.