Recommended editors #44

RealOrangeOne · 2017-12-07T10:06:34Z

Recommend some editors for students to use, and explain how to install the library on machines to get type definitions etc.

sedders123

Couple of small things

sedders123 · 2017-12-07T18:30:46Z

content/api/local-installation.md

+title: Local installation
+---
+
+Installing our code locally will allow your editor you extract type definitions from the `Robot` class and its boards, as well as allowing type completion on parameters.


to extract?

sedders123 · 2017-12-07T18:32:00Z

content/api/local-installation.md

+pip install git+https://github.com/sourcebots/robot-api --user
+```
+
+Simply restart your editor of choice, and it should these up and start being able to use them immediately.


load these up?

sedders123

Sorry should have been clearer originally

sedders123 · 2017-12-07T19:15:43Z

content/api/local-installation.md

 ---

-Installing our code locally will allow your editor you extract type definitions from the `Robot` class and its boards, as well as allowing type completion on parameters.
+Installing our code locally will allow your editor you to extract type definitions from the `Robot` class and its boards, as well as allowing auto-complete (also known as [IntelliSense](https://en.wikipedia.org/wiki/IntelliSense)).


'will allow your editor you to' The 'you' after editor should be removed

sedders123

LGTM 👍

PeterJCLaw · 2017-12-07T23:08:18Z

.spelling

 2.2A.
+PyCharm
+macOS
+IntelliSense


trailing newline please

PeterJCLaw

Looks like a good starting point, though I worry that much is too technical for many readers (see inline for details).

I'm aware that I'm not familiar with the rest of the docs, so I'm not sure how these fit in context -- if the context resolves the overly-technical side, then feel free to ignore those comments.

PeterJCLaw · 2017-12-07T23:09:32Z

content/api/local-installation.md

+
+Installing our code locally will allow your editor to extract type definitions from the `Robot` class and its boards, as well as allowing auto-complete (also known as [IntelliSense](https://en.wikipedia.org/wiki/IntelliSense)).
+
+Installing these definitions is highly optional, however will be incredibly useful if your editor supports this. All editors in our [recommended list](/tutorials/editors/) besides IDLE will support it.


"highly" feels redundant by the time users are reading this page.

PeterJCLaw · 2017-12-07T23:11:53Z

content/tutorials/editors.md

+To write code for the kit, you don't need anything specific in your editor, you just need to be able to edit Python (`.py`) files, and get them onto a USB drive.
+{{% /notice %}}
+
+Any editor will do, so it's recommended to use one you're already familiar with. If you don't already have a preference, here's some great ones, available on Windows, macOS, and Linux!


Is that the right capitalisation of macOS (I was expecting MacOS, but that's based on English grammar rules rather than Apple)

i'm afraid it is. https://www.apple.com/macos/

PeterJCLaw · 2017-12-07T23:13:04Z

content/tutorials/editors.md

+- [Visual Studio Code](https://code.visualstudio.com)
+- [PyCharm](https://jetbrains.com/pycharm/)
+- [Atom](https://atom.io/)
+- [IDLE](https://wiki.python.org/moin/IDLE) (comes with Python!)


IDLE only comes with Python on Windows I think (I've not seen it on Ubuntu, don't know about Macs)

PeterJCLaw · 2017-12-07T23:15:43Z

content/api/local-installation.md

@@ -0,0 +1,31 @@
+---
+title: Local installation


I'm not sure how it will look once rendered, but this feels ambiguous -- what is being installed.

I also wonder whether this page should be phrased more as "Getting editor support for the API" rather than "Installing the API". The difference is that the former is an intent, while the latter is a way to achieve it.

PeterJCLaw · 2017-12-07T23:24:06Z

content/api/local-installation.md

+title: Local installation
+---
+
+Installing our code locally will allow your editor to extract type definitions from the `Robot` class and its boards, as well as allowing auto-complete (also known as [IntelliSense](https://en.wikipedia.org/wiki/IntelliSense)).


While correct, the phrasing here feels quite technical. I expect that inexperienced readers would be confused by this (what's a "type definition"?).

Unless we're deliberately targetting advanced users, we should probably keep this fairly high level.

(I'd be completely open to having an "Advanced" section which explains that we have added type annotations compatible with mypy)

PeterJCLaw · 2017-12-07T23:26:51Z

content/tutorials/editors.md

+
+Any editor will do, so it's recommended to use one you're already familiar with. If you don't already have a preference, here's some great ones, available on Windows, macOS, and Linux!
+
+- [Sublime Text 3](https://sublimetext.com)


Sublime is (strictly speaking) a paid-for editor, for any use. I'd suggest that we move it down the list (or note that you're meant to buy it)

PeterJCLaw · 2017-12-07T23:29:01Z

content/tutorials/editors.md

+To edit your code, you'll need an editor.
+
+{{% notice info %}}
+To write code for the kit, you don't need anything specific in your editor, you just need to be able to edit Python (`.py`) files, and get them onto a USB drive.


Should we clarify that Python files are actually just text files?

PeterJCLaw · 2017-12-07T23:30:05Z

content/api/local-installation.md

+Installing our API, the code you interact with, can be installed using `pip`, Python's built-in package manager. `pip` should be installed on your machine, if it's not, you'll need to look up how to install it. On Windows, this is best done using the [`get-pip.py` script](https://pip.pypa.io/en/stable/installing).
+
+```bash
+pip install git+https://github.com/sourcebots/robot-api


Are we considering putting the API up on PyPI?

I remember it being discussed previously very briefly, and not really actively considered. But i'm strongly against it

PeterJCLaw · 2017-12-07T23:31:22Z

content/api/local-installation.md

+Installing these definitions is highly optional, however will be incredibly useful if your editor supports this. All editors in our [recommended list](/tutorials/editors/) besides IDLE will support it.
+
+## Installation
+Installing our API, the code you interact with, can be installed using `pip`, Python's built-in package manager. `pip` should be installed on your machine, if it's not, you'll need to look up how to install it. On Windows, this is best done using the [`get-pip.py` script](https://pip.pypa.io/en/stable/installing).


We should clarify that pip will be installed if you have installed Python. (I'm not sure whether we've already told them to do that somewhere, but even if we have I think it's worth being explicit here)

Related to this, have we mentioned anywhere that they'll need to use Python 3?

It's mentioned in #45, however i'll reitterate it here to be sure

PeterJCLaw · 2017-12-07T23:32:22Z

content/api/local-installation.md

+Installing these definitions is highly optional, however will be incredibly useful if your editor supports this. All editors in our [recommended list](/tutorials/editors/) besides IDLE will support it.
+
+## Installation
+Installing our API, the code you interact with, can be installed using `pip`, Python's built-in package manager. `pip` should be installed on your machine, if it's not, you'll need to look up how to install it. On Windows, this is best done using the [`get-pip.py` script](https://pip.pypa.io/en/stable/installing).


Are there any recent versions of Python for Windows which don't bundle pip? (If not, I suggest dropping the last sentence here).

Added commands for powershell using py -m for all bash commands

kierdavis · 2017-12-09T21:53:46Z

content/api/editor-support.md

+Installing these definitions is optional, however will be incredibly useful if your editor supports this. All editors in our [recommended list](/tutorials/editors/) besides IDLE will support it.
+
+## Installation
+Installing our API, the code you interact with, can be installed using `pip`, Python's built-in package manager. `pip` should be installed on your machine, if it's not, you'll need to look up how to install it. 


A trailing blank seems to have crept in on this line.

PeterJCLaw · 2017-12-10T11:31:46Z

content/tutorials/editors.md

 - [PyCharm](https://jetbrains.com/pycharm/)
 - [Atom](https://atom.io/)
- [IDLE](https://wiki.python.org/moin/IDLE) (comes with Python!)
+- [Sublime Text 3](https://sublimetext.com) (License recommended for continued use)


Just realised: why does Sublime Text get a version number?

PeterJCLaw · 2017-12-10T11:42:45Z

content/api/editor-support.md

 ```bash
 pip install git+https://github.com/sourcebots/robot-api
 ```
+And on windows:


I'm not sure what the cause of difference is, but I've always been able to just pip directly on windows.

It's possible this addition isnt necessary, but when I tried yesterday on @Bitbait 's windows machine, pip wasn't available in the path. I'll investigate on my windows machine(s) and see if I can find a cause

I can use pip on Windows without explicitly editing the path, the installer has a tick box (ticked by default) for auto adding installation to PATH

RealOrangeOne · 2017-12-15T22:40:29Z

This requires validation of #44 (comment) before merging.

Changes made

Add a page with kit shipping instructions

RealOrangeOne added 2 commits December 6, 2017 20:32

Add some recommended editors

da63aca

Add documentation on installing type definitions

b8154a0

RealOrangeOne requested review from Adimote, PeterJCLaw and sedders123 December 7, 2017 10:06

Cleanup editors file

d5eac82

sedders123 requested changes Dec 7, 2017

View reviewed changes

Update grammar from review

4c2306b

RealOrangeOne force-pushed the recommended-editors branch from cebc5db to 4c2306b Compare December 7, 2017 19:10

RealOrangeOne requested a review from sedders123 December 7, 2017 19:11

sedders123 requested changes Dec 7, 2017

View reviewed changes

Remove unnecessary 'you'

73871e3

RealOrangeOne requested a review from sedders123 December 7, 2017 19:18

sedders123 previously approved these changes Dec 7, 2017

View reviewed changes

PeterJCLaw reviewed Dec 7, 2017

View reviewed changes

.spelling Outdated

2.2A.

PyCharm

macOS

IntelliSense

Copy link

Contributor

PeterJCLaw Dec 7, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

trailing newline please

PeterJCLaw previously requested changes Dec 7, 2017

View reviewed changes

Cleanup and simplification of editor recommendation

96a0bfe

RealOrangeOne dismissed sedders123’s stale review via 96a0bfe December 8, 2017 18:55

RealOrangeOne requested a review from PeterJCLaw December 8, 2017 19:00

ADded windows instruction

176df7f

Added commands for powershell using py -m for all bash commands

kierdavis reviewed Dec 9, 2017

View reviewed changes

PeterJCLaw reviewed Dec 10, 2017

View reviewed changes

mildlyincompetent previously approved these changes Dec 15, 2017

View reviewed changes

Dont assume the college need --user

6cad438

RealOrangeOne dismissed mildlyincompetent’s stale review via 6cad438 December 15, 2017 22:37

mildlyincompetent previously approved these changes Dec 15, 2017

View reviewed changes

RealOrangeOne added the Frozen Won't fix this issue label Dec 15, 2017

Windows isnt a special little fruit like we thought

8e8df07

RealOrangeOne dismissed mildlyincompetent’s stale review via 8e8df07 December 16, 2017 09:16

RealOrangeOne and others added 2 commits December 16, 2017 09:20

windows is kinda special

1186db5

Reword Windows specific part

04c557e

sedders123 previously approved these changes Dec 16, 2017

View reviewed changes

Merge branch 'master' into recommended-editors

f607099

sedders123 dismissed their stale review via f607099 December 16, 2017 09:26

sedders123 previously approved these changes Dec 16, 2017

View reviewed changes

I totally didn't screw up that merge conflict

017ab52

sedders123 dismissed their stale review via 017ab52 December 16, 2017 09:42

sedders123 approved these changes Dec 16, 2017

View reviewed changes

sedders123 merged commit fb026ac into master Dec 16, 2017

sedders123 deleted the recommended-editors branch December 16, 2017 09:44

PeterJCLaw pushed a commit to PeterJCLaw/sourcebots-docs that referenced this pull request Mar 6, 2019

Merge pull request sourcebots#44 from richardbarlow/shipping_docs

6ee802e

Add a page with kit shipping instructions


		Installing our code locally will allow your editor to extract type definitions from the `Robot` class and its boards, as well as allowing auto-complete (also known as [IntelliSense](https://en.wikipedia.org/wiki/IntelliSense)).

		Installing these definitions is highly optional, however will be incredibly useful if your editor supports this. All editors in our [recommended list](/tutorials/editors/) besides IDLE will support it.


		Any editor will do, so it's recommended to use one you're already familiar with. If you don't already have a preference, here's some great ones, available on Windows, macOS, and Linux!

		- [Sublime Text 3](https://sublimetext.com)

Recommended editors #44

Recommended editors #44

Uh oh!

Conversation

RealOrangeOne commented Dec 7, 2017

Uh oh!

sedders123 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sedders123 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sedders123 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PeterJCLaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RealOrangeOne commented Dec 15, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants