Rewrite Installation in RST #1310
Conversation
Doc/install/INSTALL.rst
Outdated
| 2) Mac OS X | ||
| ------------ | ||
|
|
||
| Install Apple’s XCode suite from the App Store, and then from the Xcode options also install the optional command line utilities. |
There was a problem hiding this comment.
I believe you now do not need the full XCode suite, the command line tools alone is possible.
There was a problem hiding this comment.
See the XCode instructions we give on http://biopython.org/wiki/Download about running xcode-select --install
Doc/install/INSTALL.rst
Outdated
|
|
||
| This command will show the version of python3 present in your system. If you aren't able to find the Python software available | ||
| in your Linux system, you can download Python from the site here- `https://www.python.org/downloads/source/ <https://www.python.org/downloads/source/>`_ and select the source gzipped tarball for the version you would like to install. | ||
| For example, If you want to install Python 3.6 in your system, Look for the latest stable Python 3.6 release and Click on the "Download Gzipped source tarball". |
There was a problem hiding this comment.
Do we really want to document how to install Python from source? Better pointing elsewhere?
There was a problem hiding this comment.
I don't mind linking the python.org for instructions, but wouldn't it be an issue if we tell users to go to some link everytime for some software or for a package( like we can tell users to go to NumPy docs link for instead of explaining the installation ourselves).
There was a problem hiding this comment.
Likewise I don't want us to say any more than absolutely necessary about how to install NumPy.
(This is going to be much easier on Biopython 1.70 with pip automatically pulling in numpy if missing, see #1302 which is now merged)
There was a problem hiding this comment.
So should we point people to this for installation of Python- https://wiki.python.org/moin/BeginnersGuide?
If not, We can point to this- https://tutorial.djangogirls.org/en/python_installation
There was a problem hiding this comment.
I realised now that the page for Python Beginner's Guide is outdated and doesn't give exact instructions. Should we use the Django Girls page for Python installation?
Codecov Report
@@ Coverage Diff @@
## master #1310 +/- ##
==========================================
- Coverage 84.79% 84.78% -0.01%
==========================================
Files 319 319
Lines 49050 49050
==========================================
- Hits 41591 41587 -4
- Misses 7459 7463 +4
Continue to review full report at Codecov.
|
|
@peterjc I noticed the issue with Windows conda packages just now. In that case, should we maybe release a conda package for Biopython using conda-forge? The recipe creation process should be trivial, but I am worried about the conflict with the |
|
I also suggest putting the conda instructions as an alternative step, since I believe not everyone uses conda. |
|
Yes, already noted as a good idea on biopython/biopython.github.io#118 but it applies to the main repository too. |
|
@peterjc The Biopython conda recipe is now ready here- https://github.com/conda-forge/biopython-feedstock |
Doc/install/INSTALL.rst
Outdated
|
|
||
| $ conda install -c bioconda biopython | ||
| $ conda install -c conda-forge biopython |
There was a problem hiding this comment.
Isn't conda-forge a default channel? Can we just recommend: conda install biopython instead?
There was a problem hiding this comment.
I checked the command conda install biopython in Windows, It still fetches the 1.68 binaries uploaded to default channel.
conda install -c conda-forge biopython works really well as it fetches the latest binaries for Windows which is uploaded to the conda-forge channel.
There was a problem hiding this comment.
Ah - this is likely due to the default channel priority setting. That's fine then, thanks for checking.
|
@peterjc Do we need to make any more updates to the doc? I would like a review from someone in Biopython developer community. |
Doc/install/INSTALL.rst
Outdated
| 3) Windows | ||
| ----------- | ||
|
|
||
| We recommend you install Biopython and its dependencies using the provided pre-compiled Windows Installers. i.e. You don’t need a C compiler. |
There was a problem hiding this comment.
This is now out of date, we provide wheel files but not installers.
Doc/install/INSTALL.rst
Outdated
| @@ -111,7 +111,7 @@ UNIX/Linux | |||
| For installing Biopython, you will require a software package called ``pip`` to do so. If you are using the latest 3.x version of Python, you will have the package preinstalled in your UNIX/Linux system. You can check the version of the software by doing:: | |||
|
|
|||
| $ pip --version | |||
| pip 9.0.1 from /usr/lib/python3.6/site-packages (python 3.6) | |||
| pip 9.0.1 from /usr/lib/python3.6/site-packages (python 3.5) | |||
There was a problem hiding this comment.
This looks wrong - there is a mix of Python 3.6 and 3.5 here now (the old version was all Python 3.6)
Doc/install/INSTALL.rst
Outdated
| If there were no errors and everything worked correctly, you should now be able to type ``python`` at a command prompt and enter into the python interpreter:: | ||
|
|
||
| $ python | ||
| Python 2.7.5 (...) |
There was a problem hiding this comment.
Given the example above was installing Python 3.6.1, this is not consistent.
|
I still don't think we should describe how to install Python in our documentation, but just point at the official python.org information for that (and other popular options like conda). |
|
I didn't notice the consistency in Python version across the docs, that should be fixed by a quick correction. As for pointing users for Python installation, I remember the docs being outdated on the installation ( the docs cover Python 3.3, plus there are many inconsistencies in the docs across platforms). I suggest pointing users to Anaconda( at least that is what Software Carpentry does) for the latest Python distribution. |
|
Yes, cleaning up all the inconsistencies in the current install documentation is part of #1295. As part of this, the less extra and not important information we include, the less documentation have to maintain. |
|
Added link to Hitchhiker's Guide to Python for the installation of Python. |
Doc/install/INSTALL.rst
Outdated
| @@ -19,7 +19,7 @@ GCC is recommende as the C compiler, which is usually available as part of the s | |||
| 2) Mac OS X | |||
| ------------ | |||
|
|
|||
| Install Apple’s XCode suite from the App Store, and then from the Xcode options also install the optional command line utilities. | |||
| Install Apple’s XCode suite from the App Store, and then install the commandline tools using command- ``xcode-select --install`` on the terminal. | |||
There was a problem hiding this comment.
You don't need the XCode suite at all anymore. I think the wording on http://biopython.org/wiki/Download is still accurate (I don't have a clean Mac to double check this on, those I have access to already have the command line tools).
Also missing a space in "command line" and there is an extra minus/hyphen before the the command.
There was a problem hiding this comment.
I wasn't sure about this earlier. I confirmed this right now on a friend's Mac. Running the command itself is enough for command-line tools and installing XCode also ensures that you get the command-line tools.
There was a problem hiding this comment.
Thanks for doing that - good to know what we're recommending on http://biopython.org/wiki/Download is still current for getting the compilers on macOS 👍
|
Closing the PR since it is going nowhere |
A Work in progress fix for #1295
I have also enabled editing for maintainers in case any of the maintainer wishes to push fixes to the documentation.