Skip to content

My edits #18

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.

Sign up for GitHub

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

Open
Leviathan314159 wants to merge 17 commits into
base: main
Choose a base branch
from
Open

My edits #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
c8df4c2
Update README.md
Leviathan314159 Jun 15, 2021
498d11d
Update README.md
Leviathan314159 Jun 15, 2021
7018bbe
Update README.md
Leviathan314159 Jun 15, 2021
c6ad9e0
Update README.md
Leviathan314159 Jun 15, 2021
4616cf9
Update README.md
Leviathan314159 Jun 21, 2021
dad2c73
Update README.md
Leviathan314159 Jun 22, 2021
ecfec59
Update README.md
Leviathan314159 Jun 23, 2021
d0debcf
Update first_code.md
Leviathan314159 Jun 30, 2021
7dba539
Update first_code.md
Leviathan314159 Jun 30, 2021
dea3c15
Update first_code.md
Leviathan314159 Jun 30, 2021
a1d3941
Update python_packages.md
Leviathan314159 Jun 30, 2021
4f38468
Update python_packages.md
Leviathan314159 Jun 30, 2021
3b2a9cf
Update tox.ini
Leviathan314159 Jun 30, 2021
51b1b18
Update tox.ini
Leviathan314159 Jun 30, 2021
c39f28d
Update README.md
Leviathan314159 Jun 30, 2021
7fcf917
Update github.md
Leviathan314159 Jul 1, 2021
95168ff
Update README.md
Leviathan314159 Jul 1, 2021
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
122 changes: 62 additions & 60 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# Getting Started

A guide to getting started in the Materials Simulation Group (MSG)
with python, Travis CI, Sphinx, GitHub and general scientific
computing. This guide doesn't assume any prior programming experience.
Welcome to the Materials Simulation Group(MSG)!

This guide will help you get started with Python, Travis CI, Sphinx,
GitHub and general scientific computing. Whether you have previous programming
experience or not, we'll cover the basics you need in the group.

What follows is meant to be an introduction to the tools and skills
you need to be an effective member of the MSG group and to become a
Expand All @@ -18,8 +20,9 @@ the small amounts of code suggested in the guide, we recommend strongly that you
write it yourself to get practice. Don't just copy the existing
files.

We also recommend that you not skip any sections in this walk-through,
even if you are already familiar with the concepts.
Be sure not to skip any sections in this tutorial, even if you are already
familiar with the concepts. It will help you understand what others
in the group are doing and will save time and energy for you later.

#### Table of Contents

Expand Down Expand Up @@ -70,7 +73,7 @@ even if you are already familiar with the concepts.

## The Goal

If you are interested in joining the group, download the one of the
If you are interested in joining the group, download one of the
chapters of [Giordano's "Computational Physics"](https://msg.byu.edu/giordano) book and use the problems
in the book to practice the steps below.

Expand All @@ -82,7 +85,7 @@ integration](https://en.wikipedia.org/wiki/Continuous_integration)
coverage](https://en.wikipedia.org/wiki/Code_coverage), and [API
documentation](https://en.wikipedia.org/wiki/Application_programming_interface). If
you don't know what any of these things mean feel free to follow the
links or sit tight---we'll be there soon. This things should become clear as we cover each topic
links or sit tight---we'll be there soon. It should become clear as we cover each topic
in this walk-through.

In addition, you will be putting your code up on
Expand All @@ -103,14 +106,15 @@ account and make a repository. The directions
### Python

In this group we write most of our code in
[python](https://www.python.org/), if we need it to be faster then we
prototype it in python and then code it in
[python](https://www.python.org/). Python is a convenient programming language to work with,
but it is slower than some other languages, so if we need the code to be faster we first
prototype it in python, and then code it in
[fortran](https://en.wikipedia.org/wiki/Fortran). That being said we
execute most of our code from the terminal;
to work effectively in computational science, you should get used to working in the terminal. If you are a
Windows user we strongly recommend you get
[docker](https://www.docker.com/) for this reason. (Our group Windows expertise---we don't find Windows convenient for computation.) If you are a
mac user, you have a very nice terminal (and python) already. However, you should still get
[docker](https://www.docker.com/) for this reason. (Our group has little Windows expertise---we don't find Windows convenient for computation.) If you are a
mac user, then you already have a very nice terminal (and python). However, you should still get
[docker](https://www.docker.com/).

#### Docker
Expand All @@ -124,19 +128,20 @@ docker pull wsmorgan/python

(Note: This is a rather large download, about 400 MB total.)
This image has working copies of python 2.7, 3.4, 3.5, and 3.6. You
are welcome to develop in any of them. To access the image use:
are welcome to develop in any of them. To access the image use this command:

```
docker run --name 'my_container' --rm -i -t wsmorgan/python bash
```

Where the `my_container` variable has be replaced by a name you'll remember. This command creates a docker container with the name you
Replace the `my_container` variable with a name you'll remember (it's just a placeholder to show you the syntax).
This command creates a docker container with the name you
specify and opens an interactive bash terminal of the docker
image. The `--rm` flag means that when you exit the interactive
terminal the container will also be deleted. We will be using this
docker image through out the rest of this tutorial to run and test any
code you write. You can even develop your code from this container,
however, keep in mind that when you exit the container will be deleted
docker image throughout the rest of this tutorial to run and test any
code you write. You can even develop your code from this container!
However, keep in mind that when you exit, the container will be deleted
and any code you have not pushed to GitHub will be lost (even without
the `--rm` flag in the command you risk losing any code you wrote
while in the container). I will assume that you will be producing code
Expand All @@ -152,7 +157,7 @@ with your scripts built into it.

Before we even start to write our first program we need to get our
python package setup properly. This will allow us to easily test our
codes as we build them, a process called test driven development, and
codes as we build them (a process called test driven development) and
ensure the code behaves as we expect.

### Python Packages
Expand Down Expand Up @@ -190,13 +195,13 @@ The first thing you need to do is enable Travis CI to monitor your git
repository and run unit tests when it detects a change. To do that go
to: [https://travis-ci.org/](https://travis-ci.org/) and click on the
'Sign in with GitHub' or 'Sign up' buttons. (Either will have the same
effect. Once logged in the server should automatically start linking
effect) Once logged in the server should automatically start linking
with GitHub and listing your repositories. If it doesn't, go to your
name in the top right corner and click on the accounts option that
pops down.

Once your account has synced with GitHub you should see the repository
you created at the start of this project with grey box and `x` in a
you created at the start of this project with a grey box and `x` in a
square next to it. Click that box, it will turn blue and, the `x` will
turn into a check and voila! You've enabled Travis CI to monitor and
run the unit tests on your repository.
Expand Down Expand Up @@ -228,7 +233,7 @@ python:
```

Inform Travis CI that you will be performing tests in the python 2.7
and 3.4 environments, if these are not the python versions you want
and 3.4 environments. If these are not the python versions you want
Travis CI to run tests in then modify these lines to reflect the
python versions you are testing your code in. The next lines tell
Travis CI what it needs to install to run your tests:
Expand All @@ -241,16 +246,15 @@ install:

The `pip install .` says to install the local python package once its
been pulled to the server. Then Travis CI is told it needs to install
tox to run the tests (`pip install tox`). This format assumes that
everything your package, and its unit-tests, need to run are included
in your [setup.py](instructions/python_packages.md#setuppy) file. If
this is not the case you will need to list any additional dependencies
for your package in a another file, usually called
`requirements.txt`. The `requirements.txt` file lists each additional
python package needed for your package, or its tests, on a separate
line. For example, if your package needs numpy and scipy, and they
aren't listed in your setup.py, then your `requirements.txt` file
would look like:
tox to run the tests (`pip install tox`). This format assumes that your
[setup.py](instructions/python_packages.md#setuppy) file includes
everything your package and unit tests need to run. If this is not
the case you will need to list any additional dependencies for your
package in another file, usually called `requirements.txt`.
The `requirements.txt` file lists each additional python package needed
for your package, or its tests, on a separate line. For example, if your
package needs numpy and scipy, and they aren't listed in your setup.py,
then your `requirements.txt` file would look like:

```
numpy
Expand Down Expand Up @@ -290,8 +294,8 @@ your README.

Code coverage is a report of how many lines of code your unit-tests
cover. Your goal is to have 100% code coverage for any code you
write. There is a caveat to this idea, there are times when you will
write code that Travis CI cannot test, for example:
write. However, there is a caveat to this idea as there are times when
you will write code that Travis CI cannot test, for example:

```
def _run_from_ipython(self):
Expand Down Expand Up @@ -322,8 +326,8 @@ To make the reports produced by coverage easier to read we're going to
use a service called [CodeCov](https://codecov.io/). Go to
[https://codecov.io/](https://codecov.io/) and click `Sign up` then
`sign up with GihHub`. Once inside navigate your way to your
repositories list, it should be empty, then click `Add new
repository`. A list of all your repositories should appear, click on
repositories list, which should be empty, then click `Add new
repository`. A list of all your repositories should appear; click on
the repository you made for this project and a 2 step process will
appear on the screen. Step one will have a token for you to copy. Go
ahead and copy it, you can follow the link of examples in for
Expand Down Expand Up @@ -352,14 +356,12 @@ text to the top of your README.md right after the build status badge.

### Code Quality, Landscape

The last issue to be concerned with now that our code will be run
through a CI server and we'll be receiving coverage reports is if our
code is good quality. In other words, does our code follow standard
style guidelines, does it have any sections that are likely to break or
introduce bugs, is it easily readable.... Being able to produce good
quality code will often set you apart as a programmer. There are a
number of sites that perform code quality checks but we're going to
talk about how to use only one of them,
The last issue to be concerned with now is if our code is good quality.
In other words, does our code follow standard style guidelines, does it
have any sections that are likely to break or introduce bugs, is it easily
readable.... Being able to produce good quality code will often set you
apart as a programmer. There are a number of sites that perform code
quality checks but we're only going to talk about how to use one of them,
[Landscape](https://landscape.io/). Go to
[https://landscape.io/](https://landscape.io/) and click `Sign in with
GitHub`. On the next screen click `+ Add Repository` then from the
Expand Down Expand Up @@ -413,8 +415,8 @@ sphinx-quickstart
```

Sphinx will start and prompt you through questions. The first is
asking you where you want the information sphinx makes for you to
go. If directory doesn't exist sphinx can make it. Tell Sphinx to put
asking you where you want to put the information sphinx makes for you.
If a directory doesn't exist sphinx can make it. Tell Sphinx to put
the documentation in `docs` then press enter.

Next is a question about how to construct the build directory. This
Expand All @@ -425,9 +427,9 @@ give it the appropriate entries (when it asks for project version use
0.0 and 0.0.1 for the release).

For the rest of the questions it's best to stick with Sphinx's default
values for now, you can feel free to experiment with them later. There
are 2 exceptions, The first is that you want to enable the sphinx
autodoc extension. So when sphinx asks you `autodoc: automatically
values for now; you can feel free to experiment with them later. There
are 2 exceptions: The first is that you want to enable the sphinx
autodoc extension. When sphinx asks you `autodoc: automatically
insert docstrings from modules (y/n)` (this happens right after it
asks about 'epub') type `y` for yes. The second is you want to create
a .nojekyll file, this prompt will come up as `githubpages: create
Expand Down Expand Up @@ -474,14 +476,14 @@ cd docs
make html
```

There are many different options for building your API documentation,
There are many different options for building your API documentation;
for an example of a different setup see [aflow's docs
folder](https://github.com/rosenbrockc/aflow/tree/master/docs), as you
folder](https://github.com/rosenbrockc/aflow/tree/master/docs). As you
get more experience you should experiment with what you want your
documentation to look like. When the make has finished we're going to
copy the entire project back over to your home machine. When you do
this make sure you are in the directory that contains your GitHub
repository's folder, in other words if use:
repository's folder, in other words use:

```
ls
Expand All @@ -501,7 +503,7 @@ docs. You can now open your documentation using:
open 'get_repo/docs/_build/index.html
```

If this doesn't work don't worry, we're going to make it so that
If this doesn't work don't worry! We're going to make it so that
anyone can view the nice API documentation that Sphinx built for you.

### GitHub Pages
Expand Down Expand Up @@ -539,27 +541,27 @@ git push
```

GitHub will then prompt you for your user name and password. Now go
back to your and click on your github.io
back to your github and click on your github.io
repository. The changes you made on your local machine should now be
there. What you just did was add all the files in your local copy of
the repository to the git repository using `git add .` (you can also
add files individually by listing them after the add keyword), then you
committed them for a push using `git commit -m "Some message."` (the -m
committed them for a push using `git commit -m "Some message explaining the changes made."` (the -m
tells git that you have a message to add, if you don't use the -m then
git will open an editor of some kind for you to add a message anyway),
then finally you pushed the changes up to GitHub.

Now to make your API documentation findable to the general public we
want to add the following line to your 'README.md' file (it can go
anywhere some developers put it at the bottom of the file some near
anywhere, some developers put it at the bottom of the file some near
the top, it's up to you):

```
Full API Documentation available at: [github pages](https://'your
GitHub user name'.github.io/'my_pkg/).
```

Make sure that the project name matches the folder name your created
Make sure that the project name matches the folder name you created
in your github.io repository. With that addition your API documentation
will be readable when you make a push at the end of the next section.

Expand Down Expand Up @@ -616,13 +618,13 @@ git push
```

Now go to [GitHub](https://github.com/) and click on your project's
repository. Since GitHub automatically takes you to the master branch
repository. Since GitHub automatically takes you to the main branch
nothing will look different. To see your changes click on the
`Branch: master` button and select 'dev' from the drop-down menu. Now
all your changes should be visible. To add these changes to your master
`Branch: main` button and select 'dev' from the drop-down menu. Now
all your changes should be visible. To add these changes to your main
branch we're going to use a pull request. Near the top of the list of
files for your repository there should be a line that says something
like `this branch is 1 commit ahead of master` then a button that says
like `this branch is 1 commit ahead of main` then a button that says
'new pull request'. Click the button, on the next page find the
button that says `create pull request`. Now we wait. Come back to your
repository in 10-15 minutes and click on the pull request tab near the
Expand All @@ -633,7 +635,7 @@ initial run but that's okay) then push `merge pull request` otherwise
wait a few more minutes and check again.

Once you've merged the pull request you should see three badges appear
on your repositories README If any of them don't have the word
on your repository's README. If any of them don't have the word
'passing' or '100%' in them then figure out why and fix them.

The beauty of this approach is that it enables you to use services
Expand Down
Loading