Update docs to include instructions for multiple interpreter sessions#87
Update docs to include instructions for multiple interpreter sessions#87dhruvisompura merged 14 commits intomainfrom
Conversation
✅ Deploy Preview for positron-posit-co ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
This file used to be called interpreters.qmd. I've split the contents up so that multi session information is in the interpreters.qmd file and all the startup related information is now in this file.
I left most of the file as is but I did remove the sections that are no longer relevant due to multi sessions.
I haven't done a full audit of this file to see if it matches our style guide. I assume it mostly does. If we aren't sure - I can take another look at it!
interpreters.qmd
Outdated
| The active interpreter session can always be identified in the Interpreter picker. | ||
|
|
||
| ## Subsequent runs | ||
| <screenshot> |
There was a problem hiding this comment.
These are just placeholders for where I plan to put the screenshots. I'll update these soon!
| 3. **New session creation**: If no interpreter session exists for the document language, Positron starts a new interpreter session. See the [Interpreter startup](interpreter-startup.qmd) guide for information on how Positron handles interpreter startup for you. | ||
|
|
||
| In addition to starting up an interpreter when the workspace is first opened, Positron will also automatically start an interpreter when it looks like one is needed. For example, Python will start: | ||
| ### Language-specific features |
There was a problem hiding this comment.
I think this section could use some extra polish! Specifically, the diagnostics section. I wasn't sure what else to write there.
juliasilge
left a comment
juliasilge
left a comment
There was a problem hiding this comment.
This is looking good! Thank you so much for working on this 🙌
I have some big picture anxiety about screenshots, as I have seen the maintenance burden of these just spiral into a pretty difficult situation. We have posit-dev/positron#7651 to track some better process in this area.
For this initial version of these docs, can I ask you to:
- evaluate which of these screenshots are necessary vs. nice-to-have? i.e. do you think words/narrative could be enough for any of these, before we invest in automation for screenshots?
- consider which of these whole-app screenshots could be subsections of the app, to reduce the fallout from UI changes?
- reduce the use of annotation on these screenshots, where possible?
I know this likely doesn't feel great 🙈 but I do think it's important to try to set ourselves up for less extreme pain moving forward.
Co-authored-by: Julia Silge <julia.silge@gmail.com>
Co-authored-by: Julia Silge <julia.silge@gmail.com>
Co-authored-by: Julia Silge <julia.silge@gmail.com>
Co-authored-by: Julia Silge <julia.silge@gmail.com>
Co-authored-by: Julia Silge <julia.silge@gmail.com>
Co-authored-by: Julia Silge <julia.silge@gmail.com>
I went through the doc and removed all but 4 screenshots. I've left a single screenshot containing the whole app because I think its important for the user to see where UI is located visually. This screenshot that feels necessary to me so users have a sense of the custom UI components we are talking about. The remaining screenshots cover the location of buttons/actions that aren't immediately obvious from just looking at the IDE. I left the annotations in for the images but I can remove them if we don't want annotations for images? I assume there are accessibility benefits we get for free by using them (I haven't verified this). I'm debating if we need the icon describing the status icons. I could take or leave that one. |
juliasilge
left a comment
juliasilge
left a comment
There was a problem hiding this comment.
Fantastic! Thank you so much for all this work 🤩
2 participants
Addresses posit-dev/positron#6214
Updated the docs related to interpreters to include information about multi session support.
I think we've landed on the term
Interpreter sessioninstead ofconsole sessionso references to that have been updated in the doc.I tried to follow our Posit style guide which also recommends the Microsoft style guide for describing UI.
There may be some mistakes around bolding/referencing UI elements as proper nouns so extra eyes on that would be helpful.