Clarifies single line for Python 2 and 3

[stsievert]

Added a section to the transition guide that clarified a script can include one line to run under both Python 2 and Python 3. IMHO, this helps with the impression the "transition" to Python 3 is not a huge step for scientists.

[stephtdouglas]

I'm not sure this needs to be a separate section - it's mostly duplicating the first paragraph under 'Making the transition easier'. Perhaps it would be better to edit the existing text for clarity?

I also agree with @ngoldbaum that "vanilla Python" is unclear, and it may come across as a little condescending too. Perhaps just saying "typical scientific Python scripts"?

[astrofrog]

I agree that I'm not sure this should be in a separate section. If average users put this in a script, things will break because they haven't updated e.g. print statements. But there may be ways we can make the following section less intimidating and make it clearer it's a very easy change. I think fundamentally we do want to make sure that people realize it's an easy step in most cases, I understand the motivation of this PR.

[stsievert]

we do want to make sure that people realize it's an easy step in most cases

@astrofrog that's exactly the motivation.

In the recent changes, the biggest thing I've done is switched "transitioning to Python 3" to "Writing Python 3 compatible code".

[adrn]

@stsievert The section covers more than just writing Python 3 compatible code -- why the name change?

[stsievert]

The section covers more than just writing Python 3 compatible code @adrn

But writing Python 3 compatible code is transitioning to Python 3.

I know my transition to Python 3 only involved putting parens around my print statements. I avoided Python 3 because I thought it'd be a big change; when I realized that it was a small change I transitioned quickly.

I'm trying to make the transition seem less like a weekend project, and more like a couple small syntax changes (which for scientific Python tends to be true).

All the existing sections can be thought of as "how to write Python 3 compatible code".

@ngoldbaum I deleted the doc link because it was showing as a plain URL. I tried to get it to show as a highlighted __future__ but couldn't make it work.

[ngoldbaum]

I'd just do something like this:

diff --git a/python3_user_transition_guide.rst b/python3_user_transition_guide.rst
index 95a9bab..180dbf5 100644
--- a/python3_user_transition_guide.rst
+++ b/python3_user_transition_guide.rst
@@ -12,7 +12,7 @@ you can take towards switching. Thankfully, the most disruptive changes to the
 language have been back-ported to Python 2 so you can ensure that, when writing
 new code that you intend to execute with Python 2, it will be executable in
 Python 3 once you switch. To use these back-ported changes, you must import
-certain utilities from the built-in ```__future__``
+certain utilities from the `built-in __future__
 <https://docs.python.org/2/library/__future__.html>`_ package. It is generally
 recommended that, if you are still writing Python 2 compatible code, you should
 import the following four modules in any code you write

[adrn]

@stsievert For example, the section on using conda environments doesn't really fit under "how to write Python 3 compatible code" -- I'd prefer to just keep it as is, or restructure. But I don't think the latter is necessary. What do others think?

[astrofrog]

(As mentioned in #4, I think we could actually move the conda section to a dedicated page)