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

Update how-to-use document to provide information on conda env setup #199

Merged
merged 4 commits into from
Dec 23, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 28 additions & 7 deletions preamble/how-to-use.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,11 +86,30 @@ and select “.ipynb”.

That was the easy part. Getting the notebook to execute locally may
take a little more work. The book was created to run in a particular
Python environment, managed with Conda. To ensure success you should
follow the instructions in the Pythia Foundations contributor’s
[guide](https://foundations.projectpythia.org/appendix/how-to-contribute.html)
on how to configure your Python environment. Once your environment
is configured and “activated”, change your working directory to the
Python environment, managed with Conda. If you don't have a up-to-date
version of Conda on your machine, you'll want to install one. A brief
introduction to installing Conda is available [here](https://foundations.projectpythia.org/foundations/conda.html).

Once you've installed Conda you will need to create and activate a Conda environment
that is compatible with Pythia Foundation's notebooks. This
can be done with two commands from the terminal, one to create the
environment and one to activate it:

```
conda env create --force -f https://raw.githubusercontent.com/ProjectPythia/pythia-foundations/main/environment.yml
conda activate pythia-book-dev
```

You should only need to create the environment once (run the first
command above). But if you download another notebook later, you will
need to activate _pythia-book-dev_ if
it is not currently active, for example if you open up a new
terminal window, or deactivate _pythia-book-dev_ explicitly with
the `conda` command. Again, more information on Conda can be
found [here](https://foundations.projectpythia.org/foundations/conda.html).

Now that your _pythia-book-dev_ environment is activated,
change your working directory to the
location where you downloaded the notebook (.ipynb file) and start
the Jupyter Notebook server. For example if you downloaded the
notebook file to your home directory you would do:
Expand All @@ -102,11 +121,13 @@ notebook file to your home directory you would do:

A local Jupyter Notebook server should open in your web browser.
Simply open the .ipynb file using the Notebook server’s file browser
and you are good to go. Alternatively, you could “clone the site”
and you are good to go. If you want to work with many Pythia Foundations
notebooks, you might want to “clone the site”
and download all of the notebooks. First click on the Pythia
Foundations GitHub icon (see figure below) and select repository.
Then follow the instructions in our Getting Started with GitHub
[guide](https://foundations.projectpythia.org/foundations/getting-started-github.html#)
for cloning a repository.
for cloning a repository. The steps used above for configuring your
Conda environment should work for this method as well.

![Annotated Pythia Foundations home page](../images/foundations_diagram.png)