19 Sitio web

Hasta este punto, hemos analizado muchas formas de documentar su paquete:

Documentación de funciones o, más generalmente, temas de ayuda (Capítulo 16).
Documentación de conjuntos de datos (Sección 7.1.2).
Viñetas (y artículos) (Capítulo 17).
LÉAME y NOTICIAS (Capítulo 18).

¿No sería divino si todo eso de alguna manera se reuniera en un hermoso sitio web para su paquete? El paquete pkgdown está destinado a proporcionar exactamente esta magia y ese es el tema de este capítulo.

19.1 Iniciar un sitio

Suponiendo que su paquete tiene una estructura válida, pkgdown debería poder crear un sitio web para él. Obviamente, ese sitio web será más sustancial si su paquete tiene más elementos de documentación enumerados anteriormente. Pero algo razonable debería suceder con cualquier paquete R válido.

Tip

Escuchamos que algunas personas posponen el “aprendizaje de pkgdown” porque creen que les supondrá mucho trabajo. ¡Pero finalmente ejecutan los dos comandos que mostramos a continuación y tienen un sitio web decente en menos de cinco minutos!

usethis::use_pkgdown() es una función que se ejecuta una vez y realiza la configuración inicial mínima necesaria para comenzar a usar pkgdown:

usethis::use_pkgdown()

#> ✔ Setting active project to '/tmp/RtmpsmyYn2/mypackage'
#> ✔ Adding '^_pkgdown\\.yml$', '^docs$', '^pkgdown$' to '.Rbuildignore'
#> ✔ Adding 'docs' to '.gitignore'
#> ✔ Writing '_pkgdown.yml'
#> • Edit '_pkgdown.yml'
#> ✔ Setting active project to '<no active project>'

Esto es lo que hace use_pkgdown():

Crea _pkgdown.yml, que es el archivo de configuración principal para pkgdown. En una sesión interactiva, se abrirá _pkgdown.yml para su inspección y edición. Pero no hay necesidad inmediata de cambiar o agregar nada aquí.
Agrega varios patrones a .Rbuildignore, para evitar que archivos y directorios específicos de pkgdown se incluyan en su paquete.
Agrega docs, el destino predeterminado para un sitio renderizado, a .gitignore. Esto es inofensivo para quienes no usan Git. Para aquellos que lo hacen, esto los habilita para nuestro estilo de vida recomendado, donde la fuente definitiva para su sitio pkgdown se crea y se implementa en otro lugar (probablemente a través de GitHub Actions and Pages; más sobre esto pronto). Esto significa que el sitio web renderizado en docs/ solo sirve como vista previa local.

pkgdown::build_site() es una función que llamará repetidamente para volver a representar su sitio localmente. En un paquete extremadamente básico, verá algo como esto:

pkgdown::build_site()

#> ✔ Setting active project to '/tmp/RtmpsmyYn2/mypackage'
#> ── Installing package mypackage into temporary library ─────────────
#> ── Building pkgdown site for package mypackage ─────────────────────────────────
#> Reading from: /tmp/RtmpsmyYn2/mypackage
#> Writing to: /tmp/RtmpsmyYn2/mypackage/docs
#> ── Initialising site ───────────────────────────────────────────────────────────
#> Copying
#> ../../../home/runner/work/_temp/renv/cache/v5/linux-ubuntu-jammy/R-4.4/x86_64-pc-linux-gnu/pkgdown/2.0.9/8bf1151ed1a48328d71b937e651117a6/pkgdown/BS5/assets/link.svg
#> and
#> ../../../home/runner/work/_temp/renv/cache/v5/linux-ubuntu-jammy/R-4.4/x86_64-pc-linux-gnu/pkgdown/2.0.9/8bf1151ed1a48328d71b937e651117a6/pkgdown/BS5/assets/pkgdown.js
#> to link.svg and pkgdown.js
#> ── Building home ───────────────────────────────────────────────────────────────
#> Writing `authors.html`
#> Writing `404.html`
#> ── Building function reference ─────────────────────────────────────────────────
#> Writing `reference/index.html`
#> Writing sitemap.xml
#> ── Building search index ───────────────────────────────────────────────────────
#> ── Finished building pkgdown site for package mypackage ────────────────────────
#> ── Finished building pkgdown site for package mypackage ────────────
#> ✔ Setting active project to '<no active project>'

In an interactive session your newly rendered site should appear in your default web browser.

RStudio

Otro buen gesto para construir su sitio es a través de Addins > pkgdown > Build pkgdown.

Puede buscar en el directorio local docs/ para ver los archivos que constituyen el sitio web de su paquete. Para navegar manualmente por el sitio, abra docs/index.html en su navegador preferido.

Esto es casi todo lo que realmente necesitas saber sobre pkgdown. Sin duda, es un gran comienzo y, a medida que su paquete y sus ambiciones crezcan, el mejor lugar para obtener más información es el sitio web creado por pkgdown para el paquete pkgdown en sí: https://pkgdown.r-lib.org.

19.2 Despliegue

Su próxima tarea es desplegar su sitio pkgdown en algún lugar de la web, para que sus usuarios puedan visitarlo. El camino de menor resistencia se ve así:

Utilice Git y aloje su paquete en GitHub. Las razones para hacer esto van mucho más allá de ofrecer un paquete de sitio web, pero este será uno de los principales beneficios de adoptar Git y GitHub, si no está seguro.
Utilice GitHub Actions (GHA) para crear su sitio web, es decir, para ejecutar pkgdown::build_site(). GHA es una plataforma donde puedes configurar ciertas acciones para que sucedan automáticamente cuando ocurre algún evento. Lo usaremos para reconstruir su sitio web cada vez que acceda a GitHub.
Utilice GitHub Pages para servir su sitio web, es decir, los archivos que ve debajo de docs/ localmente. GitHub Pages es un servicio de alojamiento de sitios web estáticos que crea un sitio a partir de archivos que se encuentran en un repositorio de GitHub.

Los consejos para usar GitHub Action y Pages se implementan en la función usethis::use_pkgdown_github_pages(). No es una tarea especialmente difícil, pero hay varios pasos y sería fácil pasar por alto alguno o fallar. La salida de use_pkgdown_github_pages() debería verse así:

usethis::use_pkgdown_github_pages()
#> ✔ Initializing empty, orphan 'gh-pages' branch in GitHub repo 'jane/mypackage'
#> ✔ GitHub Pages is publishing from:
#> • URL: 'https://jane.github.io/mypackage/'
#> • Branch: 'gh-pages'
#> • Path: '/'
#> ✔ Creating '.github/'
#> ✔ Adding '^\\.github$' to '.Rbuildignore'
#> ✔ Adding '*.html' to '.github/.gitignore'
#> ✔ Creating '.github/workflows/'
#> ✔ Saving 'r-lib/actions/examples/pkgdown.yaml@v2' to '.github/workflows/pkgdown.yaml'
#> • Learn more at <https://github.com/r-lib/actions/blob/v2/examples/README.md>.
#> ✔ Recording 'https://jane.github.io/mypackage/' as site's url in '_pkgdown.yml'
#> ✔ Adding 'https://jane.github.io/mypackage/' to URL field in DESCRIPTION
#> ✔ Setting 'https:/jane.github.io/mypackage/' as homepage of GitHub repo 'jane/mypackage'

Al igual que use_pkgdown(), esta es una función que básicamente llamas una vez, cuando configuras un nuevo sitio. De hecho, lo primero que hace es llamar a use_pkgdown() (está bien si ya has llamado a use_pkgdown()), por lo que normalmente saltamos directamente a use_pkgdown_github_pages() cuando configuramos un sitio nuevo.

Veamos qué hace realmente use_pkgdown_github_pages():

Inicializa una rama vacía y “huérfana” en tu repositorio de GitHub, denominada gh-pages (para “Páginas de GitHub”). La rama gh-pages solo vivirá en GitHub (no hay razón para buscarla en su computadora local) y representa un universo paralelo separado de la fuente real de su paquete. Los únicos archivos rastreados en gh-pages son aquellos que constituyen el sitio web de su paquete (los archivos que ve localmente debajo de docs/).
Activa GitHub Pages para tu repositorio y le indica que proporcione un sitio web a partir de los archivos que se encuentran en la rama gh-pages.
Copia el archivo de configuración para un flujo de trabajo de GHA que realiza pkgdown “compilado e implementado”. El archivo aparece en su paquete como .github/workflows/pkgdown.yaml. Si es necesario, se realizan algunas adiciones relacionadas a .gitignore y .Rbuildignore.
Agrega la URL de su sitio como página de inicio de su repositorio de GitHub.
Agrega la URL de su sitio a DESCRIPCIÓN y _pkgdown.yml. El comportamiento de enlace automático que hemos promocionado en otros lugares depende de que su paquete incluya su URL en estos dos lugares, por lo que esta es una configuración de alto valor.

Después de la ejecución exitosa de use_pkgdown_github_pages(), debería poder visitar su nuevo sitio en la URL que se muestra en el resultado anterior.¹ Por defecto, la URL tiene esta forma general: https://USERNAME.github.io/REPONAME/.

19.3 ¿Ahora qué?

Para un paquete típico, podría detenerse aquí, después de crear un sitio de pkgdown básico y organizar su reconstrucción e implementación con regularidad — y las personas que usen (o consideren usar) su paquete se beneficiarían enormemente. Todo lo que pase más allá de este punto es “un placer tenerlo”.

En general, recomendamos vignette("pkgdown", package = "pkgdown") como un buen lugar para comenzar, si cree que quiere ir más allá de los valores predeterminados básicos.

En las secciones siguientes, destacamos algunas áreas que están conectadas con otros temas del libro o personalizaciones que son particularmente gratificantes.

19.4 Logotipo

¡Es divertido tener un logotipo de paquete! En la comunidad R, tenemos una fuerte tradición de pegatinas hexagonales, por lo que puede ser bueno unirte con tu propio logotipo hexagonal. La usuaria de Keen R, Amelia McNamara, se hizo un vestido con tela con logotipo hexagonal personalizado y useR! 2018 presentó un espectacular muro de fotografías hexagonales.

Aquí hay algunos recursos para guiar sus esfuerzos de logotipo:

La convención es orientar el logo con un vértice en la parte superior e inferior, con lados verticales planos.
Si cree que podría imprimir pegatinas, asegúrese de cumplir con el estándar de facto para el tamaño de las pegatinas. hexb.in es una fuente confiable para las dimensiones y también proporciona una lista de proveedores potenciales de pegatinas impresas.

Figura 19.1: Dimensiones estándar de una pegatina hexagonal.
El paquete hexSticker te ayuda a crear tu logotipo desde la comodidad de R.

Una vez que tenga su logotipo, la función usethis::use_logo() coloca una copia a escala adecuada del archivo de imagen en man/figures/logo.png y también proporciona un fragmento de descuento que se puede copiar y pegar para incluir su logotipo. en su README. pkgdown también descubrirá un logotipo colocado en la ubicación estándar y lo incorporará a su sitio.

19.5 Índice de referencia

pkgdown crea una referencia de función en reference/ que incluye una página para cada tema de ayuda .Rd en man/. Esta es una de las primeras páginas que debes admirar en tu nuevo sitio. Al mirar a su alrededor, hay algunas cosas que considerar, que repasamos a continuación.

19.5.1 Ejemplos renderizados

pkgdown ejecuta todos sus ejemplos (Sección 16.5) e inserta los resultados renderizados. Creemos que esto es una mejora fantástica con respecto a mostrar simplemente el código fuente. Esta vista de sus ejemplos puede resultar reveladora y, a menudo, notará cosas que desea agregar, omitir o cambiar. Si no está satisfecho con la apariencia de sus ejemplos, este es un buen momento para revisar técnicas para incluir código que se espera que dé error (Sección 16.5.3) o que solo se puede ejecutar bajo ciertas condiciones (Sección 16.5.4).

19.5.2 Vinculación

Estos temas de ayuda estarán vinculados desde muchas ubicaciones dentro y, potencialmente, más allá de su sitio pkgdown. De esto es de lo que estamos hablando en Sección 16.1.3 cuando recomendamos poner funciones entre corchetes al mencionarlas en un comentario de roxygen:

#' Soy un gran admirador de [estaduncion()] en mi paquete. I
#' también tengo algo que decir sobre [otropqt::otrafuncion()]
#' en el paquete de otra persona.

En los sitios de pkgdown, esas funciones entre corchetes se convierten en hipervínculos a las páginas relevantes de su sitio de pkgdown. Esto es automático dentro de su paquete. Pero los enlaces entrantes de paquetes de otras personas (y sitios web, etc.) requieren dos cosas²:

El campo URL de su archivo DESCRIPTION debe incluir la URL de su sitio pkgdown (preferiblemente seguida de la URL de su repositorio de GitHub):
```
URL: https://dplyr.tidyverse.org, https://github.com/tidyverse/dplyr
```
Su archivo _pkgdown.yml debe incluir la URL de su sitio:
```
URL: https://dplyr.tidyverse.org
```

devtools aprovecha cada oportunidad que tiene para realizar este tipo de configuración por usted. Pero si elige hacer las cosas manualmente, esto es algo que podría pasar por alto. Un recurso general sobre el enlace automático en pkgdown es vignette("linking", package = "pkgdown").

19.5.3 Organización del índice

De forma predeterminada, el índice de referencia es solo una lista de funciones ordenada alfabéticamente. Para paquetes con más de un puñado de funciones, a menudo vale la pena seleccionar el índice y organizar las funciones en grupos. Por ejemplo, dplyr utiliza esta técnica: https://dplyr.tidyverse.org/reference/index.html.

Esto se logra proporcionando un campo de reference en _pkgdown.yml. Aquí hay un extracto redactado del archivo _pkgdown.yml de dplyr que le da una idea de lo que implica:

reference:
- title: Data frame verbs

- subtitle: Rows
  desc: >
    Verbs that principally operate on rows.
  contents:
  - arrange
  - distinct
  ...

- subtitle: Columns
  desc: >
    Verbs that principally operate on columns.
  contents:
  - glimpse
  - mutate
  ...

- title: Vector functions
  desc: >
    Unlike other dplyr functions, these functions work on individual vectors,
    not data frames.
  contents:
  - between
  - case_match
  ...

- title: Built in datasets
  contents:
  - band_members
  - starwars
  - storms
  ...

- title: Superseded
  desc: >
    Superseded functions have been replaced by new approaches that we believe
    to be superior, but we don't want to force you to change until you're
    ready, so the existing functions will stay around for several years.
  contents:
  - sample_frac
  - top_n
  ...

Para obtener más información, consulte ?pkgdown::build_reference.

19.6 Viñetas y artículos

Capítulo 17 trata sobre viñetas, que son guías detalladas para un paquete. Ofrecen varias oportunidades más allá de lo que es posible en la documentación de funciones. Por ejemplo, tienes mucho más control sobre la integración de la prosa y el código y sobre la presentación del código en sí; por ejemplo, el código puede ejecutarse pero no verse, verse pero no ejecutarse, etc. Es mucho más fácil crear la experiencia de lectura que mejor prepare a sus usuarios para el uso auténtico de su paquete.

Las viñetas de un paquete aparecen, en formato renderizado, en su sitio web, en el menú desplegable Articles. “Viñeta” parece un término técnico que no esperamos que todos los usuarios de R conozcan, razón por la cual pkgdown utiliza el término “artículos” aquí. Para ser claros, el menú Articles enumera las viñetas oficiales de su paquete (las que están incluidas en su paquete) y, opcionalmente, otros artículos que no son viñetas (Sección 17.4.1), que solo están disponibles en el sitio web. .

19.6.1 Vinculación

Al igual que la documentación de funciones, las viñetas también pueden ser el objetivo de enlaces entrantes automáticos desde dentro de su paquete y, potencialmente, más allá. Hemos hablado de esto en otra parte del libro. En Sección 16.1.3, introdujimos la idea de hacer referencia a una viñeta con una llamada en línea como vignette("some-topic"). La razón detrás de esta sintaxis es que el código se puede literalmente copiar, pegar y ejecutar para ver la viñeta local. Por tanto, “funciona” en cualquier contexto, incluso sin enlaces automáticos. Pero, en contextos donde la maquinaria de enlace automático está disponible, sabe buscar esta sintaxis exacta y convertirla en un hipervínculo a la viñeta asociada, dentro de un sitio pkgdown.

La necesidad de especificar el paquete de host depende del contexto:

vignette("some-topic"): utilice este formulario en sus propios comentarios, viñetas y artículos de roxygen para hacer referencia a una viñeta en su paquete. El paquete de host está implícito.
vignette("some-topic", package = "somepackage"): Utilice esta forma para hacer referencia a una viñeta en algún otro paquete. El paquete de host debe ser explícito.

Tenga en cuenta que esta abreviatura no funciona para vincular a artículos que no son viñetas. Dado que la sintaxis se apoya tanto en la función vignette(), sería demasiado confuso, es decir, evaluar el código en la consola fallaría porque R no podrá encontrar dicha viñeta. Los artículos que no sean viñetas deben vincularse como cualquier otra URL.

Cuando haga referencia a una función en su paquete, en sus viñetas y artículos, asegúrese de ponerla entre comillas invertidas e incluir paréntesis. Califica funciones de otros paquetes con su espacio de nombres. A continuación se muestra un ejemplo de prosa en una de sus propias viñetas o artículos:

Soy un gran admirador de `thisfunction()` en mi paquete. yo también tengo algo que
decir sobre `otherpkg::otherfunction()` en el paquete de otra persona.

Recuerde que los enlaces entrantes automáticos de paquetes de otras personas (y sitios web, etc.) requieren que su paquete anuncie la URL de su sitio web en DESCRIPTION y _pkgdown.yaml, según lo configurado por usethis:: use_pkgdown_github_pages() y como se describe en Sección 19.5.2.

19.6.2 Organización del índice

Al igual que con el índice de referencia, la lista predeterminada de los artículos (definidos en sentido amplio) en un paquete es alfabética. Pero si su paquete tiene varios artículos, puede valer la pena brindarle una organización adicional. Por ejemplo, puede presentar los artículos dirigidos al usuario típico y colocar aquellos destinados a usuarios avanzados o desarrolladores detrás de “Más artículos …”. Puede obtener más información sobre esto en ?pkgdown::build_articles.

19.6.3 Artículos que no son viñetas

En general, Capítulo 17 es nuestra principal fuente de consejos sobre cómo abordar las viñetas y eso también incluye cierta cobertura de artículos que no son viñetas (Sección 17.4.1). Aquí revisamos algunas razones para utilizar un artículo que no sea una viñeta y damos algunos ejemplos.

Un artículo es moralmente como una viñeta (por ejemplo, cuenta una historia que involucra múltiples funciones y está escrita con R Markdown), excepto que no se envía con el paquete. usethis::use_article() es la forma más sencilla de crear un artículo. La razón principal para utilizar un artículo es cuando desea mostrar código que es imposible o muy doloroso de incluir en una viñeta o ejemplo oficial. Posibles causas fundamentales de este dolor:

Uso de un paquete del que no desea depender formalmente. En viñetas y ejemplos, está prohibido mostrar su paquete funcionando con un paquete que no incluye en DESCRIPTION, por ejemplo, en Imports o Suggests.

Hay un ejemplo detallado de esto en Sección 11.7.2, que presenta un artículo readxl que utiliza el metapaquete tidyverse. La idea clave es enumerar dicha dependencia en el campo Configuración/Necesidades/sitio web de DESCRIPTION. Esto mantiene a tidyverse fuera de las dependencias de readxl, pero garantiza que se instale cuando se crea el sitio web.
Código que requiere autenticación o acceso a activos, herramientas o secretos específicos que no están disponibles en CRAN.

El paquete googledrive no tiene viñetas verdaderas, solo artículos que no son viñetas, porque es esencialmente imposible demostrar su uso sin autenticación. Es posible acceder a variables de entorno seguras en GitHub Actions, donde se crea e implementa el sitio pkgdown, pero esto es imposible de hacer en CRAN.
Contenido que involucra muchas cifras, lo que hace que su paquete choque con las limitaciones de tamaño de CRAN.

El paquete ggplot2 presenta varias preguntas frecuentes como artículos por este motivo.

19.7 Modo de desarrollo

Cada sitio de pkgdown tiene un llamado modo de desarrollo, que se puede especificar a través del campo development en _pkgdown.yml. Si no se especifica, el valor predeterminado es “mode: release”, lo que da como resultado un único sitio pkgdown. A pesar del nombre, este sitio único refleja el estado del paquete fuente actual, que podría ser un estado publicado o un estado de desarrollo. El siguiente diagrama muestra la evolución de un paquete hipotético que está en CRAN y que tiene un sitio pkgdown en modo “release”.

...
 |
 V
Tweaks before release     v0.1.9000
 |
 V
Increment version number  v0.2.0     <-- install.packages() selecciona esta
 |
 V
Increment version number  v0.2.9000  
 |
 V
Improve error message     v0.2.9000  <-- site documenta esta
 |
 V
...

Los usuarios que instalan desde CRAN obtienen la versión 0.2.0. Pero el sitio pkgdown se construye a partir de la versión de desarrollo del paquete.

Esto crea la posibilidad de que los usuarios lean sobre alguna característica nueva en el sitio web que no está presente en la versión del paquete que han instalado con install.packages(). Descubrimos que la simplicidad de esta configuración supera las desventajas, hasta que un paquete tiene una base de usuarios amplia, es decir, muchos usuarios de distintos niveles de sofisticación. Probablemente sea seguro permanecer en el modo “liberar” hasta que escuche a un usuario confundido.

Los paquetes con una base de usuarios sustancial deben utilizar el modo de desarrollo “auto”:

development:
  mode: auto

Esto indica a pkgdown que genere un sitio de nivel superior a partir de la versión publicada y que documente la versión de desarrollo en un subdirectorio dev/. Revisamos el mismo paquete hipotético que el anterior, pero asumiendo que el sitio pkdown está en modo “auto”.

...
 |
 V
Tweaks before release     v0.1.9000
 |
 V
Increment version number  v0.2.0     <-- install.packages() selecciona esta
 |                                       main/ site documenta esta
 V
Increment version number  v0.2.9000  
 |
 V
Improve error message     v0.2.9000  <-- dev/ site documenta esta
 |
 V
...

Todos los paquetes principales de tidyverse utilizan el modo “auto”. Por ejemplo, considere el sitio web del paquete readr:

readr.tidyverse.org documenta la versión publicada, es decir, lo que ofrece install.packages("readr").
readr.tidyverse.org/dev/ documenta la versión de desarrollo, es decir, lo que ofrece install_github("tidyverse/readr").

Se recomienda el modo de desarrollo automático para paquetes con una amplia base de usuarios, porque maximiza la posibilidad de que un usuario lea documentación basada en web que refleje la versión del paquete que está instalada localmente.

A veces hay un pequeño retraso, así que espere un par de minutos para implementarlo.↩︎
Otro requisito previo es que su paquete haya sido publicado en CRAN, porque la maquinaria de enlace automático tiene que buscar la DESCRIPTION en alguna parte. Es posible permitir que los paquetes instalados localmente se vinculen entre sí, lo cual se describe en vignette("linking", package = "pkgdown").↩︎