Get Started > Positron #1692
Get Started > Positron #1692
Conversation
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-1692.quarto.org 🔄 Modified Documents |
|
Howdy @cwickham -- would this be OK to rollout by the start of July? Any review of revisions we can help with? |
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-1692.quarto.org 🔄 Modified Documents |
📝 Preview Deployment🔍 Full site preview: https://deploy-preview-1692.quarto.org 🔄 Modified Documents |
|
I've opened quarto-dev/quarto-cli#13010 for a future where we can get people up and running with all the documents and packages with a single (or sequence) of Positron commands. |
There was a problem hiding this comment.
This is looking so great! 🎉
I really like the tabset treatment on these pages and think the new minimal CSS treatment is really nice in this context. I am a bit worried about the first time there is one on the page with the very minimal tabset treated as a switcher; it looks so understated that I myself was a bit confused about what it was supposed to me. It might just be me, though; maybe we can show this to a few more people to see if it's clear to them what to do.
| ::: {.panel-tabset group="language"} | ||
|
|
||
| ## R | ||
|
|
||
| ## Python | ||
|
|
||
| ::: |
There was a problem hiding this comment.
I have kind of mixed feelings about having a tabset without content in it set up to use as a chooser, and worry that it is not a typical enough website gesture for folks to understand. Maybe we can get another set of eyes on whether this makes sense? Would it be better if there was some content in it?
There was a problem hiding this comment.
Agreed. I'm guessing this couldn't be a radio button, as the selection then carries through to other tabsets. Could this particular tabset be styled differently with CSS to make it look like a radio button or like boxes on top of the page for tool selection? Alternatively, adding some descriptor text would resolve the issue too. Maybe something like "If you primarily code in R, select this tab to see code examples in R. You can always switch over to Python whenever you like throughout the guide."
There was a problem hiding this comment.
I've tweaked the CSS so these first tabsets are more obviously buttons. Added some content in the tabset to clarify too.
|
|
||
| ## R | ||
|
|
||
| {.column-page-right .border fig-alt="Positron with a Quarto document titled \"Penguins, meet Quarto!\" open on the left side and the rendered version of the document on the right side." fig-align="center"} |
There was a problem hiding this comment.
When I view these in the deploy preview, the screenshots go past the main content area out on the left, which is different from the same content on the other IDE pages and does not interact well with the TOC. Is it possible for us to treat these screenshots more similarly to the screenshots of other IDEs?
There was a problem hiding this comment.
Related to screenshots, can you say a bit more about using dark mode for all of these? I think I would want to advocate for the default Positron theme, unless there is a particular reason for going with dark mode here.
There was a problem hiding this comment.
the screenshots go past the main content area out on the left
This was intentional (and consistent with RStudio, but not VS Code). For the screenshots of the whole IDE its nice to have a bit more room so the content of the screenshot isn't too tiny. When only one pane is in the screenshot, I've intentionally kept the image from expanding into the margin. The TOC does collapse, but it is still available from the "On this page" dropdown.
There was a problem hiding this comment.
can you say a bit more about using dark mode for all of these?
With quarto.org now having light and dark mode, ideally we'd have screenshots in Positron that match the site, i.e. dark mode in Positron, for dark mode on quarto.org. I'd stuck to dark mode for this round since dark screenshots in light mode are slightly less offensive to the eyes than light screenshots in dark mode. Once the content in finalized I can do another pass of screenshots in both light and dark.
There was a problem hiding this comment.
Is the yellow background on the screenshots in this PR intentional? I think I would prefer to see the more typical white.
There was a problem hiding this comment.
No, not intentional...I'll figure this out.
There was a problem hiding this comment.
Looks great, made some suggestions throughout.
A couple of more comments:
-
Switching between R and Python tabs make the page jump, but there may be nothing to be done about that.
-
I couldn't make an inline suggestions for these since they weren't edited during this PR:
-
under
## Citationsin_text-editor.md: "To cite other works within a Quarto document. First create a bibliography" = "To cite other works within a Quarto document, first create a bibliography" -
"Cross References" = "Cross-References" in
_text-editor.md.
-
| ::: {.panel-tabset group="language"} | ||
|
|
||
| ## R | ||
|
|
||
| ## Python | ||
|
|
||
| ::: |
There was a problem hiding this comment.
Agreed. I'm guessing this couldn't be a radio button, as the selection then carries through to other tabsets. Could this particular tabset be styled differently with CSS to make it look like a radio button or like boxes on top of the page for tool selection? Alternatively, adding some descriptor text would resolve the issue too. Maybe something like "If you primarily code in R, select this tab to see code examples in R. You can always switch over to Python whenever you like throughout the guide."
|
|
||
| ::: | ||
|
|
||
| You can read more, and see some syntax alternatives, at [Markdown Basics: Source Code](/docs/authoring/markdown-basics.qmd#source-code) |
There was a problem hiding this comment.
| You can read more, and see some syntax alternatives, at [Markdown Basics: Source Code](/docs/authoring/markdown-basics.qmd#source-code) | |
| You can read more and see some syntax alternatives at [Markdown Basics: Source Code](/docs/authoring/markdown-basics.qmd#source-code). |
|
|
||
| ## R | ||
|
|
||
| To include executable expressions within markdown text, enclose the expression in `` `{r} ` ``^[Quarto also supports the Knitr syntax `` `r ` ``, read more in [Inline Code](/docs/computations/inline-code.qmd)]. |
There was a problem hiding this comment.
| To include executable expressions within markdown text, enclose the expression in `` `{r} ` ``^[Quarto also supports the Knitr syntax `` `r ` ``, read more in [Inline Code](/docs/computations/inline-code.qmd)]. | |
| To include executable expressions within markdown text, enclose the expression in `` `{r} ` ``^[Quarto also supports the Knitr syntax `` `r ` ``, read more in [Inline Code](/docs/computations/inline-code.qmd).]. |
| If the expression you want to inline is more complex, involving many functions or a pipeline, we recommend including it in a code cell (with `echo: false`) and assigning the result to an object. | ||
| Then, you can call that object in your inline code. | ||
|
|
||
| For additional details on inline code expressions, visit the [Inline Code](/docs/computations/inline-code.qmd) page. |
There was a problem hiding this comment.
| For additional details on inline code expressions, visit the [Inline Code](/docs/computations/inline-code.qmd) page. | |
| For additional details on inline code expressions, visit the [Inline Code](/docs/computations/inline-code.qmd) documentation. |
|
@mine-cetinkaya-rundel and @juliasilge, I made some changes to the language picker. How do you feel about it here: https://deploy-preview-1692.quarto.org/docs/get-started/hello/positron.html ? Thanks for all the feedback, I think I've addressed it all now. I still need to do a full round of screenshots (light and dark, no yellow tint) before merging. |
|
That looks great to me! |
Audience
For Positron users, assume these are people who work with data (as opposed to VS Code flow, where readers might be software developers, or more scientific computing types).
Assume no prior knowledge of similar systems, e.g. RMarkdown.
Summary
This is mostly a reuse and blend of the RStudio and VS Code flows with the following big modifications:
computations/positron.qmd- it felt like there was too much material in this one so I trimmed heavily. Added a "Cell Workflow" section.Thoughts and questions
Can we add some CSS to minimize the appearance of the tabsets? I.e. I want to keep the tab headers (although maybe they could move to right), but would like to have tab content inline with other content (i.e. not indented). Done
The example doc doesn't show computational output in the initial screenshot. Should we re-write to move a code cell earlier? A bit more like: https://quarto.org/index.html#python-tab. Yes, it removes dependency on an external image, and helps cement the purpose of computational cells.
It might be nice to include more advanced features in the example doc like a cross-reference, or a caption. Now includes cross-reference.
Would Python users be put off by using
plotnineas opposed to something likematplotlib? (I personally like that the two example documents look identical despite the language used to create them). Verdict is, no, this is fine.Currently, this is mostly a "look at this tutorial". Should it involve more doing? I.e. "Edit the heading and re-render". No problems with first page being mostly "look at this". Next steps, could be more "do this".