Skip to content
Snippets Groups Projects
Select Git revision
  • a260c413393aa02b0aad034008bdea0b302cf2a2
  • master default
  • issue#2
  • issue#4
  • issue#1
5 results

cap06.Rmd

Blame
    • cap06.Rmd 6.26 KiB 
    title: "Vinhetas"
author: "Fernando Mayer & Walmes Zeviani"
    library(knitr)

opts_chunk$set(
    dev.args=list(family = "Palatino"))

options(width = 68)

## Carrega as definições de sessão.
source("config.R")
rty <- "md"

    Adicionando vinheta

    Brainstorm

    Vignette - vinheta - esboço - episódio.

    O jeito antigo de fazer pacote:

    O que são as vinhetas?

    • Documentação extendida do pacote? De certa forma sim.
    • Uma documentação menos pontual e mais geral? Sim.
    • Substitui um artigo? Não, pois artigos não exibem código;
    • É uma propaganda do pacote? Sem dúvida.
    • A melhor forma de apresentar uma introdução geral do pacote.
    • Pode dar detalhes técnicos que não caberiam na documentação.
    • Pode demonstrar aspectos que não documentação não seria possível porque lá só tem código de input.
    • Uma vinheta é livre para ter figuras, links, gifs, tabelas, listas, até app shiny e gráficos dinâmicos como o googleVis.

    Elas ficam no diretório vignettes/. São parte do sistema de ajuda/documentação do pacote.

    As entradas com % no YAML são ignoradas pelo LaTex e processadas pelo R para gerar links na home da documentação (suponho).

    A vantagem do HTML é que uma index pode dar acesso às várias vinhetas de um pacote. Torna fácil para o usuário iniciante.

    ## Exibe as vinhetas disponíveis.
vignette()

## Acessa uma vinheta.
vignette("lala")

sistem.file("lala", package="lulu")

browseVignettes("YourPackage")

    A coisa que mais fácil ajuda você a conhecer as funcionalidades de um pacote é sem dúvida a sua vinheta (vignette). Um pacote pode ter várias vinhetas, cada uma exibindo um tema diferente de funcionalidades.

    Produzir a vinheta de um pacote é tão fácil quanto as demais partes dele. Usaremos os recursos disponíveis no devtools mais uma vez.

    A vinheta será escrita em r renderUrl("RmarkDown","http://rmarkdown.rstudio.com/",rty). Escrever vinhetas têm uma excelente r renderUrl("documentação","http://r-pkgs.had.co.nz/vignettes.html",rty).

    A vantagem de escrever em MarkDown é a velocidade, praticidade e poder obter vinhetas em html e pdf facilmente.

    ## DESCRIPTION antes do use_vignette().
cat(readLines("./meupacote/DESCRIPTION"), sep = "\n")
    library(devtools)

## Cria a primeira vinheta do pacote.
use_vignette("minhaVinheta1")
    if (file.exists("./meupacote/vignettes/minhaVinheta1.Rmd")){
    file.remove("./meupacote/vignettes/minhaVinheta1.Rmd")
}
library(devtools)
use_vignette("minhaVinheta1", pkg = "./meupacote/")
    ## DESCRIPTION depois do use_vignette().
cat(readLines("./meupacote/DESCRIPTION"), sep = "\n")

    O comando use_vignette() cria o diretório vignettes/ com um arquivo .Rmd com o nome que você usou. Além disso ele adiciona ao campo Suggests no DESCRIPTION os pacotes knitr e rmarkdown, necessários para gerar a vinheta.

    ## Mostra diretório e arquivos criados.
cat(system("tree --charset=ascii ./meupacote/ | head -n -2",
           intern = TRUE), sep = "\n")

    Esse arquivo é criado já com conteúdo para poder orientá-lo. No topo do arquivo tem uma parte de meta dados escrita em YAML (yet another markup language) que detalha as informações do documento e definem o processo de sua criação.

    ## Mostra o YAML da vinheta original.
cat(readLines("./meupacote/vignettes/minhaVinheta1.Rmd")[1:10],
    sep = "\n")

## Nada entrou no .Rbuildignore.
## cat(readLines("./meupacote/.Rbuildignore"),
##     sep = "\n")

    Edite à vontade esse arquivo fazendo a melhor propaganda possível do seu pacote. Tome cuidado com os pacotes que vai usar. É indicado que eles estejam nos campos do seu DESCRIPTION, senão no Imports, pelo menos no Suggests. Abaixo o arquivo que criamos, que está muito simples, logicamente, mas é apenas para marcar território mesmo.

    TODO trocar essa vinheta por uma da função baskara() com os métodos.

    file.copy(from = "aux/minhaVinheta1.Rmd",
          to = "meupacote/vignettes/minhaVinheta1.Rmd",
          overwrite = TRUE)
    ## Mostra a vinheta mínima.
cat(readLines("./meupacote/vignettes/minhaVinheta1.Rmd"),
    sep = "\n")

    Para produzir a vinheta, use o comando build_vignettes(). Ele vai gerar as vinhetas de cada arquivo e levá-las para outro diretório, como pode ser visto abaixo. Caso você não tenha um dos seguintes pacotes: evaluate, formatR, highr, knitr, mime, stringi; será necessário instalá-los.

    build_vignettes()
    ## FIXME: Não existe como sair desse erro! De usar o output do
## build_vignettes().
x <- capture.output(build_vignettes("./meupacote/"))
cat(x, sep = "\n")

sink("aux.txt")
build_vignettes("./meupacote/")
sink()
    Building meupacote vignettes
Moving minhaVinheta1.html, minhaVinheta1.R to inst/doc/
Copying minhaVinheta1.Rmd to inst/doc/

    TODO Incluir a vinheta do pitagoras() ou outra funcionalidade com output em PDF.

    Por fim, basta executar check() e build() mais uma vez para incluir as vinhetas no .tar.gz do seu pacote.