Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new options for installation and improve instructions for NEST #1262

Merged
merged 16 commits into from
Nov 23, 2019

Conversation

jessica-mitchell
Copy link
Contributor

This pull request incorporates several changes to the 'onboarding and installation-related' pages of documentation.
This includes new instructions for several 'package managers', a troubleshooting section, and a modified getting-started page. See output here: https://nest-test.readthedocs.io/en/improve_installation/installation/index.html

  1. Added tabs so users can switch between desired install procedure
  2. Currently the tabs are split into two main groups, standard install and advanced
    2.1) Standard install include the Ubuntu PPA, docker, Conda and the live media (windows)
  • I do not have the brew instructions explicitly here because they have not been updated since 2.14, and we've had problems installing nest on Mojave with this method

2.2) Advanced install includes a

  • link to the instructions to compile nest on Linux,
  • the mac installation instructions (these instructions may need to be checked because of difficulties installing with this method on Mojave)
  • link to GitHub and the workflow for GitHub
  • link to HPC instructions (these need to be assessed if they are still valid)
  1. The installation page links to two main further sections - the getting-started page, which shows a simple simulation in nest, along with a more detailed breakdown of that example so new users can get a sense of the commands in nest. Thanks to @AlexVanMeegen for some of his tutorial material.
    There is also a troubleshooting page that tries to cover the main issues people have when installing nest, namely environment and package issues.
    We regularly have questions from users because of misunderstandings with installation environments. The idea with the troubleshooting page is to have a place to point people when these questions arise, that hopefully provide some useful tips, so they can fix their environment.
    @terhorstd and I have discussed this, and we think the troubleshooting page could be a separate entity from a FAQ page, where the FAQ is focused on NEST specific questions and the troubleshooting page is aimed at system or environment issues.
  2. The download page has been updated with link to 2.18 versions

@AlexVanMeegen
Copy link
Contributor

Looks great! Thanks a lot for this. Minor comments:

  1. To me,
python
import nest

is a bit confusing; I'd prefer to split the two commands to make it explicit that the latter is run in the python shell.

  1. In the first sentence in the getting_started page is a duplicate question mark: "Have you already installed NEST??"

  2. Are there somewhere instructions how to get the virtual machine fired up on windows? Just to give a bit more than the plain download link.

@terhorstd terhorstd added ZC: Documentation DO NOT USE THIS LABEL I: No breaking change Previously written code will work as before, no one should note anything changing (aside the fix) ZP: PR Created DO NOT USE THIS LABEL S: High Should be handled next T: Enhancement New functionality, model or documentation labels Aug 5, 2019
@terhorstd terhorstd added this to the NEST 2.18.1 milestone Sep 2, 2019
@jougs jougs requested review from jougs and removed request for heplesser and terhorstd October 11, 2019 09:07
@jougs jougs removed their assignment Oct 11, 2019
Copy link
Contributor

@jougs jougs left a comment

Choose a reason for hiding this comment

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

My review comments are now contained in a PR against your branch. Sorry again for this taking a century.

Remove superfluous files and streamline new installation documentation in general
Copy link
Contributor

@jougs jougs left a comment

Choose a reason for hiding this comment

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

Many thanks. I really think this is a huge improvement for getting started.

@terhorstd terhorstd changed the title Add new options for installation and improve instructions for nest Add new options for installation and improve instructions for NEST Nov 23, 2019
@terhorstd terhorstd merged commit f93b5a0 into nest:master Nov 23, 2019
@jessica-mitchell jessica-mitchell deleted the improve_installation branch March 30, 2021 08:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
I: No breaking change Previously written code will work as before, no one should note anything changing (aside the fix) S: High Should be handled next T: Enhancement New functionality, model or documentation ZC: Documentation DO NOT USE THIS LABEL ZP: PR Created DO NOT USE THIS LABEL
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants