plotly / documentation

Issue tracker for Plotly's open-source documentation.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Need to remove reliance on api_create when generating docs with RMarkdown

rpkyle opened this issue · comments

Currently, generating R documentation in this repository requires a call to api_create, e.g.

library(plotly)

p <- plot_ly(data = iris, x = ~Sepal.Length, y = ~Petal.Length)

# Create a shareable link to your chart
# Set up API credentials: https://plot.ly/r/getting-started
chart_link = api_create(p, filename="scatter-basic")
chart_link

We should modify the documentation generation such that the api_create call is no longer necessary. This will likely require the following:

  • enumerating the minimal and sufficient set of package dependencies required for all examples
  • editing 112 plot_ly-related scripts, as well as 42 ggplot2-related scripts
  • debugging any RMarkdown issues which arise, so that the process is error-free
  • opening a PR in this repository to use a Pandoc template with RMarkdown without api_create, by editing the necessary bits of _posts/r and _posts/ggplot2

The end goal is to migrate this procedure to CircleCI, such that the process is automated. @nicolaskruchten

Exciting!

Yes for the example above, in an ideal world it would look like

library(plotly)
plot_ly(data = iris, x = ~Sepal.Length, y = ~Petal.Length)

or

library(plotly)
p <- plot_ly(data = iris, x = ~Sepal.Length, y = ~Petal.Length)
p

whichever is more idiomatic

Please note that in general, each code block should be independently runnable, so there is likely going to be a lot of duplication like library(plotly) loaded up again and again... this is normal :)

You may come across missing datasets and stuff like this as you go through it... I have no generalized advice other than "make do" ;) basically try to find the original or something that serves the same purpose or just delete the example if you really really can't make it work.

Hi @CanerIrfanoglu ! Any update on this issue? :)

Hi @nicolaskruchten 🙋🏻‍♂️

I created the example .Rmd file below. Then ran Rscript -e 'rmarkdown::render("test.Rmd")' to create a .md file from it. I would appreciate getting your or @rpkyle's feedback/validation before applying the same method to the remaning examples to avoid possible multiple iterations on all the examples. Thanks :)

---
title: Group By in R | Examples | Plotly
name: Group By
permalink: r/group-by/
description: How to use groupby transforms in R with Plotly.
layout: base
thumbnail: thumbnail/groupby.jpg
language: r
has_thumbnail: true
display_as: transforms
page_type: example_index
order: 2
output:
  html_document: 
    keep_md: yes
---

```{r, echo = FALSE, message=FALSE}
knitr::opts_chunk$set(
  message = FALSE,
  warning = FALSE,
  fig.width = 8.33, # ~800px
  fig.height = 6.25 # 600px
)
library(plotly)
packageVersion('plotly')

Basic Example

library(plotly)

p <- plot_ly(x=1:4, y=runif(4))
p

So in principle this is right but I think we'd want to target HTML as an output format rather than Markdown. What file did you base this one on? It looks fairly different from https://plot.ly/r/group-by/

I changed the content of the group-by example just for testing purposes. I am able to remove the api_create and generate the figures on individual examples. Running into a problem when trying to integrate them when serving the docs locally though. As soon as that is figured, I can start editing all the examples.

I finished making requested changes towards removing the reliance of api_create at #1581. Please let me know for any possible modifications required. Thanks :)

@rpkyle @nicolaskruchten

This issue has been addressed.