Refurbish installation instructions #682
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Also link extension list in handbook itself. This is the best one around.
Incorporating the latest wisdom and helpers. The principle idea is to go from specific to generic, in order to let readers with less expertise find working solutions more quickly, while not hiding alternatives with better system-integration potential for more experienced users.
Primarily to have its in-text references resolve in the PDF
adswa
approved these changes
Mar 7, 2021
docs/intro/installation.rst
Outdated
Comment on lines
30
to
40
| DataLad requires Python 3.6, or a more recent version, to be installed on | ||
| your system. Python 2 is an outdated, in technical terms "deprecated", | ||
| version of Python. Although it still exist as the default Python version on | ||
| many systems, it is no longer maintained since 2020, and thus, most software | ||
| has dropped support for Python 2. If you only run Python 2 on your system, | ||
| most Python software, including DataLad, will be incompatible, and hence | ||
| unusable, resulting in errors during installation and execution. | ||
|
|
||
| The easiest way to verify that this is the case is to open a terminal and | ||
| type :command:`python` to start a Python session:: | ||
|
|
There was a problem hiding this comment.
Suggested change
| DataLad requires Python 3.6, or a more recent version, to be installed on | |
| your system. Python 2 is an outdated, in technical terms "deprecated", | |
| version of Python. Although it still exist as the default Python version on | |
| many systems, it is no longer maintained since 2020, and thus, most software | |
| has dropped support for Python 2. If you only run Python 2 on your system, | |
| most Python software, including DataLad, will be incompatible, and hence | |
| unusable, resulting in errors during installation and execution. | |
| The easiest way to verify that this is the case is to open a terminal and | |
| type :command:`python` to start a Python session:: | |
| Python 2 is an outdated, in technical terms "deprecated", | |
| version of Python. Although it still exist as the default Python version on | |
| many systems, it is no longer maintained since 2020, and thus, most software | |
| has dropped support for Python 2. If you only run Python 2 on your system, | |
| most Python software, including DataLad, will be incompatible, and hence | |
| unusable, resulting in errors during installation and execution. | |
| DataLad requires Python 3.6, or a more recent version, to be installed on | |
| your system. | |
| The easiest way to verify that this is the case is to open a terminal and | |
| type :command:`python` to start a Python session:: | |
How about moving the first sentence to the end of the paragraph? (looks like a large diff in the suggestion here, but I have just moved the sentence). I think this would connect the first paragraph better to the find-out-more header, the the next section on checking python versions to the requirement of Py 3.6 and higher.
There was a problem hiding this comment.
Good point! Maybe moving all of Python2 to the end is another approach -- this info will become less and less relevant over time.
There was a problem hiding this comment.
I pushed an alternative.
Co-authored-by: Adina Wagner <adina.wagner@t-online.de>
in #682 (review) With the same overall goal: better connect version info and test. But move all PY2 info to the end, anticipating that it will get more and more irrelevant over time.
|
@yarikoptic @jwodder I will merge this now, to be able to continue in related work, but please leave your comments, if you see potential for better. Thx! |
|
Thx for the review @adswa ! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Incorporating the latest wisdom and helpers.
The principle idea is to go from specific to generic, in order to let
readers with less expertise find working solutions more quickly, while
not hiding alternatives with better system-integration potential for
more experienced users.
Fixes #677
@yarikoptic @jwodder If you have advice on what to do differently, please let me know.