Update the RMG Installation Documentation #1534

amarkpayne · 2019-01-18T03:05:17Z

Motivation or Problem

There are a few issues with our current documentation for installing RMG as we found out at the RMG Workshop 2019. We also lack documentation for installation on the Ubuntu subsystem on Windows 10, which appears to be a viable route for people who cannot run a virtual machine. This PR aims to address these problems, as well as clean up and improve the documentation in general.

codecov · 2019-01-18T03:54:22Z

Codecov Report

Merging #1534 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #1534   +/-   ##
=======================================
  Coverage   42.01%   42.01%           
=======================================
  Files         165      165           
  Lines       27873    27873           
  Branches     5680     5680           
=======================================
  Hits        11711    11711           
  Misses      15377    15377           
  Partials      785      785

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 72fb120...2c67fbe. Read the comment docs.

amarkpayne · 2019-01-21T02:20:42Z

I think this PR is ready for review now. There are two things I was also considering adding to this PR:

A link to a Linux tutorial for Windows users new to Linux.
Docker images with RMG installed in them, and documentation for it.

If either of these features would be worth including, let me know and I'll add them (I was on the fence about adding both).

alongd

Looking good! See some minor comments

alongd · 2019-01-22T16:50:33Z

documentation/source/users/rmg/installation/anacondaDeveloper.rst

@@ -4,12 +4,19 @@
 Installation by Source Using Anaconda Environment for Unix-based Systems: Linux and Mac OSX
 *******************************************************************************************

-* Download and install the `Anaconda Python Platform <https://www.anaconda.com/download/>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). When prompted to append Anaconda to your PATH, select or type Yes.  Install the Anaconda folder inside your home directory (typically ``/home/YourUsername/`` in Linux and ``/Users/YourUsername`` in Mac).
+* Download and install the `Anaconda Python Platform <https://www.anaconda.com/download/>`_ for Python 2.7 (make sure not to install Python 3.0+, which is incompatible with RMG). **When prompted to append Anaconda to your PATH, select or type Yes**.  Install the Anaconda folder inside your home directory (typically ``/home/YourUsername/`` in Linux and ``/Users/YourUsername`` in Mac). You do NOT need to install Microsoft VSCode.


Re VSCode, maybe note for context something like:
You do NOT need to install Microsoft VSCode (you will be prompted to by the installer)

Do we want to add a line saying that they can install it if they need an editor? I think VSCode is the best lightweight IDE currently available.

alongd · 2019-01-22T16:52:13Z

documentation/source/users/rmg/installation/anacondaDeveloper.rst

@@ -20,36 +27,34 @@ Installation by Source Using Anaconda Environment for Unix-based Systems: Linux
  For Linux users: ::

    cd RMG-Py
+    source ~/.bashrc


Why is this needed?

Most of the time, users install Anaconda and do not open a new terminal before trying to create the conda environment. This causes an error because while anaconda was added to their path, they need to re-source their .bashrc file for bash to recognize the conda command. There is never any harm in re-sourcing your .bashrc file, and this saves new bash users some headache. Experienced Linux users will be able to decide if they need this line or not.

Alternatively, I can just add a note below this saying something like "If you get an error about the command conda not being found, then make sure that it is in your .bashrc and resource your .bashrc"

OK (no need to add further explanation)

alongd · 2019-01-22T17:39:35Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

@@ -0,0 +1,43 @@
+.. _ubuntuSubsystem:


Why do we call it Ubuntu Subsystem? The official name is "Windows Subsystem for Linux". I think that "Linux Subsystem" is a good short name

I'll make this change, thanks for the suggestion!

alongd · 2019-01-22T17:40:11Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

+<https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. The basic steps include enabling the Windows Linux
+subsystem from a powershell **run as an administrator**, and downloading the latest LTS version of Ubuntu
+*from the Windows store*. We highly recommend Ubuntu over the other Linux distros, as Ubuntu is used by many of the
+RMG developers.


Add something like (note that a Linux subsystem can only be installed on Windows 10 build 16215 or later)

Good catch! Hopefully most people are on this build by now, but it is certainly worth adding to the documentation.

alongd · 2019-01-22T17:40:48Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

+1. Follow the instructions provided by Microsoft to install the Ubuntu subsystem, available `here
+<https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. The basic steps include enabling the Windows Linux
+subsystem from a powershell **run as an administrator**, and downloading the latest LTS version of Ubuntu
+*from the Windows store*. We highly recommend Ubuntu over the other Linux distros, as Ubuntu is used by many of the


distros = distributions?

Correct, I'll make this change for clarity.

alongd · 2019-01-22T17:41:54Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

+<https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_. The basic steps include enabling the Windows Linux
+subsystem from a powershell **run as an administrator**, and downloading the latest LTS version of Ubuntu
+*from the Windows store*. We highly recommend Ubuntu over the other Linux distros, as Ubuntu is used by many of the
+RMG developers.


instead of We highly recommend Ubuntu over the other Linux distros, as Ubuntu is used by many of the RMG developers., maybe just: We recommend Ubuntu (for which these instructions were made) over the other Linux distributions?

alongd · 2019-01-22T17:43:45Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

+*from the Windows store*. We highly recommend Ubuntu over the other Linux distros, as Ubuntu is used by many of the
+RMG developers.
+
+2. Once the Ubuntu subsystem is installed, open an Ubuntu terminal. Open a web browser in Windows and go to the


Maybe direct them to first copy the link, then open a terminal to paste it?
Also, is it worth noting one of the ways of opening a terminal in Ubuntu?

Good suggestions, I have made this more clear

alongd · 2019-01-22T17:46:40Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

+    sudo apt install make
+    sudo apt-get install libxrender1
+
+5. Follow the instructions for either the binary or source installation for the Linux Operating system.


If their the same, maybe direct to one of them and specify exactly what point to continue from.

I have added the links here, but maybe we should have a discussion about what we should recommend to users when they are trying to choose between the RMG binaries or from source.

alongd · 2019-01-22T17:49:41Z

documentation/source/users/rmg/installation/virtualMachineSetup.rst

+1. Restart the PC. As soon as the PC turns back on, enter the BIOS settings (this usually involves pressing the ``F2``
+or ``F12`` keys, but will depend on your make/model). If you see the computer loading Windows then you have missed the
+opportunity, and should restart the PC to try again. If Secure Boot is enabled on your PC then there may be additional
+steps to reaching the BIOS settings.


The last sentence needs a tiny addition, perhaps something like which you should look for online?

I added an additional link here

alongd · 2019-01-22T17:50:26Z

documentation/source/users/rmg/installation/virtualMachineSetup.rst

+
+**Note that changing your BIOS settings can be risky, so follow online tutorials carefully**. If you are unsure of what
+to do even after looking for online tutorials, consider following the instructions for installing RMG inside the Linux
+subsystem in Windows.


I also added a link here to these instructions

alongd · 2019-01-22T17:53:29Z

I think a Linux tutorial link is harmless, and should probably be added.
What do we think of the RMG docker images? Were they successful at the workshop? Or were users limited?

mliu49 · 2019-01-22T18:03:45Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

+
+Install the anaconda2 folder inside your home directory (it should be the default location when it asks for a location
+to install). **When prompted to append Anaconda to your PATH, select or type Yes**. You do NOT need to install Microsoft
+VSCode.


Here, perhaps we should say explicitly to not install VSCode, and to do it directly from Windows if they want it.

mliu49 · 2019-01-22T18:09:14Z

documentation/source/users/rmg/installation/ubuntuSubsystem.rst

+of ``Anaconda2-2018.12-Linux-x86_64.sh`` to match the name of the script you downloaded. ::
+
+    chmod 744 Anaconda2-2018.12-Linux-x86_64.sh
+    ./Anaconda2-2018.12-Linux-x86_64.sh


I prefer calling bash directly: bash Anaconda2-2018.12-Linux-x86_64.sh. I feel like it's easier for users since they don't need chmod. I would recommend changing it for all of the other pages as well.

Great suggestion!

mliu49 · 2019-01-22T18:12:26Z

documentation/source/users/rmg/installation/virtualMachineSetup.rst

+First, check to see if virtualization technology is currently enabled on your computer by opening the Task Manager in
+Windows. Click on the ``Performance`` tab--from here you can see if virtualization technology is enabled.
+
+.. image:: images/Virtualization_Enabled.png


Missing image?

Sorry, I forgot that images were in the .gitignore file

mliu49 · 2019-01-22T18:12:44Z

documentation/source/users/rmg/installation/virtualMachineSetup.rst

+in your BIOS settings.
+
+First, check to see if virtualization technology is currently enabled on your computer by opening the Task Manager in
+Windows. Click on the ``Performance`` tab--from here you can see if virtualization technology is enabled.


Does this work for Windows 7?

No it does not, only for Windows 8 and later. I have added the appropriate instructions for Windows 7 and earlier.

mliu49 · 2019-01-22T18:18:33Z

We don't have any first-hand experience with RMG docker images. It was reportedly successful for the high-performance computing cluster at Auburn, where it was set up by their sysadmins. We would need more time to investigate that as an option for general users.

amarkpayne · 2019-01-22T20:06:05Z

I have made the requested changes, let me know what you guys think. I will look into using docker images, but I think this is best left to another PR.

amarkpayne · 2019-01-25T22:52:44Z

If there aren't any objections, I'll go ahead and squash the fix-up commits to get this ready to merge. If I need to make additional changes let me know though.

- Ensure that basic compilers are installed - Ensure that .bashrc is updated after installing Anaconda - Update .bashrc PATH additions - rmg.py is now called in the exact same way as the binary version for consistency

alongd · 2019-01-30T14:55:08Z

documentation/source/users/rmg/installation/index.rst

+    linuxSubsystem
+
+For users unfamiliar with bash or Linux, we recommend looking at online tutorials such as the one
+`here <https://www.guru99.com/unix-linux-tutorial.htmlhttps://www.guru99.com/unix-linux-tutorial.html>`_. To start out


Is the link here duplicated on purpose?
(could you compile the documentation and make sure all links work?)

No, this is a mistake. Thanks for the catch!

I checked the remaining links and they all seemed to work. I am pretty sure that I checked them before, but most browsers are also able to deal with this duplication properly. I also looked through the code, and this was the only duplication I found.

alongd · 2019-01-30T15:47:55Z

OK, looks good to me! @mliu49, any comments?

mliu49

Looks good to me!

amarkpayne mentioned this pull request Jan 18, 2019

Arkane Error with Source Install using "Bash on Ubuntu on Windows 10" #1516

Closed

amarkpayne self-assigned this Jan 18, 2019

amarkpayne added Type: Documentation Platform: Windows Topic: Installation Complexity: Low Status: Blocked This PR should not be merged Platform: Linux and removed Platform: Linux labels Jan 18, 2019

amarkpayne force-pushed the doc_updates branch from b7c4f85 to ff89659 Compare January 18, 2019 03:54

amarkpayne force-pushed the doc_updates branch from ff89659 to 30ceb91 Compare January 21, 2019 01:40

amarkpayne added Status: Ready for Review PR is complete and ready to be reviewed and removed Status: Blocked This PR should not be merged labels Jan 21, 2019

amarkpayne requested a review from alongd January 21, 2019 02:17

alongd reviewed Jan 22, 2019

View reviewed changes

mliu49 reviewed Jan 22, 2019

View reviewed changes

amarkpayne force-pushed the doc_updates branch from 1072434 to 6ce0ff2 Compare January 22, 2019 20:05

amarkpayne force-pushed the doc_updates branch 2 times, most recently from 6b6d3a2 to 338a4d9 Compare January 27, 2019 05:41

amarkpayne added 4 commits January 30, 2019 07:35

Update Developer's Installation Documentation

2ceef13

- Ensure that basic compilers are installed - Ensure that .bashrc is updated after installing Anaconda - Update .bashrc PATH additions - rmg.py is now called in the exact same way as the binary version for consistency

Add Installation Instructions for Ubuntu Subsystem in Windows 10

383d7a5

Add Instructions to Enable Virtualization Technology in the BIOS

6eb122f

Add Details for Anaconda Installation Instructions

cd57212

amarkpayne force-pushed the doc_updates branch from 338a4d9 to cb8f2eb Compare January 30, 2019 12:35

alongd reviewed Jan 30, 2019

View reviewed changes

Add a Link for Linux Tutorials for New Users

2c67fbe

amarkpayne force-pushed the doc_updates branch from cb8f2eb to 2c67fbe Compare January 30, 2019 15:09

mliu49 approved these changes Jan 30, 2019

View reviewed changes

alongd merged commit b7e9d1c into master Jan 30, 2019

alongd deleted the doc_updates branch January 30, 2019 19:55

mliu49 mentioned this pull request May 15, 2019

RMG v2.4.0 (?) Release Planning #1591

Closed

5 tasks

Update the RMG Installation Documentation #1534

Update the RMG Installation Documentation #1534

Conversation

amarkpayne commented Jan 18, 2019

Motivation or Problem

codecov bot commented Jan 18, 2019 • edited Loading

Codecov Report

amarkpayne commented Jan 21, 2019

alongd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alongd commented Jan 22, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mliu49 commented Jan 22, 2019

amarkpayne commented Jan 22, 2019

amarkpayne commented Jan 25, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alongd commented Jan 30, 2019

mliu49 left a comment

Choose a reason for hiding this comment

codecov bot commented Jan 18, 2019 •

edited

Loading