diff --git a/README.md b/README.md index f4e1b93..6171f2d 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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. @@ -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 @@ -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 @@ -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 @@ -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 @@ -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. @@ -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: @@ -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 @@ -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): @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -539,19 +541,19 @@ 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): ``` @@ -559,7 +561,7 @@ 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. @@ -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 @@ -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 diff --git a/instructions/first_code.md b/instructions/first_code.md index 8fc2016..c233f2b 100644 --- a/instructions/first_code.md +++ b/instructions/first_code.md @@ -36,42 +36,41 @@ The first thing that appears is `def square(x):` this defines a function called square which takes a single argument x. Everything underneath this definition that is indented is part of the function. The documentation for the function, all the text in -triple quotes, comes next. This in the sphinx google style +triple quotes, comes next. This is according to the sphinx google style documentation. Since documenting code is extremely important I will explain how it usually works. -Documentation is always started with and ends with triple double -quotes and comes immediately after the function, function, or -classes definition. The first thing inside the documentation is a +Documentation always starts with and ends with three double +quotes and comes immediately after the definition of the function +or class. This is also often referred to as a docstring. +The first thing inside the documentation is a brief description of what the function should do. After that the input, or arguments, of the function are listed below the `Args:` -tag. Each argument is listed so that it's name appears first followed -by it's type in parenthesis. After the arguments type a description of +tag. Each argument is listed so that its name appears first, followed +by its type in parentheses. After the argument's type should follow a description of what the argument is, i.e., a number to be squared, a list to be -sorted, an instance of a class ...., appears. Once all the arguments -have been listed the variables that the function returns also need +sorted, an instance of a class ..... Once all the arguments +have been listed, the variables that the function returns also need to be described using the same format. There is additional information -you can include in the function's documentation like if it raises -any exception or errors (ValueErrors, TypeErrors, ...) and examples of -usage examples of which can be found +you can include in the function's documentation, like if it raises +any exception or errors (ValueErrors, TypeErrors, ...). Some examples of this can be found [here](http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). -Once you are done with the documentation comes your actual code. This -sample function is extremely simple consisting of a single line of -code, this will not be the case most of the time. +Once you are done with the documentation, you write your actual code. This +sample function is extremely simple, consisting of a single line of +code, however this will not be the case most of the time. ## Writing unit-tests -Having written this first function we need to test it to ensure it -functions. We will do that using the python packages tox and pytest, -tox helps to automate unit tests over multiple python versions while -pytest is a package containing many tools that help us write unit -tests. Tox is a python package that handles unit testing in multiple +Having written this first function we need to test it to ensure it works properly. +We will do that using the python packages tox and pytest. +Tox is a python package that handles unit testing in multiple python versions ensuring your code will be compatible with the python -versions you desire. +versions you desire. Pytest is a package containing many tools that help +us write unit tests. To make our first unit test we will go to the directory containing -your setup.py and setup.cfg files. Once there make a new directory +your setup.py and setup.cfg files. Once there, make a new directory called tests and navigate into it: ``` @@ -85,7 +84,7 @@ start with the word `test`. For this first test lets make the file `test_my_pkg.py`. Inside the file write the following code: ``` -"""Tests the mathematical functions defined in my_pkg/trail.py +"""Tests the mathematical functions defined in my_pkg/trial.py """ import pytest @@ -99,14 +98,14 @@ def test_square(): ``` The first thing in our testing code file is a line of documentation -describing what the tests in it will do, this is optional but +describing what the tests in it will do. While this is optional, it is generally a good idea as it helps other developers know what is going on. Next we import pytest and define a function `test_square`. The name is not arbitrary. Just like the file name for tests, each function that contains tests also needs to start with the name `test`. (Anything can come after test.) Otherwise, pytest and tox will not find the tests when they are run. Inside the function we give a -description of what it will do then import the function that is +description of what it will do, then import the function that is going to be tested: ``` @@ -134,8 +133,8 @@ assert 2 == round(square(sqrt(2)), 5) It is usually a good idea to have each test check for a different possible case where the code could break. For example, here we test to make sure that our function correctly computes the square of negative numbers, fractions and -irrational numbers. We want to try and break our code with these tests so -we can fix it now rather than later. +irrational numbers. We want to try to make our code fail now so we can correct problems +sooner and more easily. ## Tox @@ -146,7 +145,7 @@ what to do. Go back up a directory to where setup.py is: cd ../ ``` -Here we will make a file called [tox.ini](../tox.ini) as sample of which +Here we will make a file called [tox.ini](../tox.ini) a sample of which can be found in the getting_started repository (or by following the link). The example file looks like this: @@ -167,30 +166,32 @@ commands= The first two lines of the file tell tox which python environments you want to test your code in. It's usually a good idea to check that your code runs in python 2, since many users haven't switched to python 3 -yet, and in one or two python 3 versions. The sample file tells tox to +yet, and there are a few version of python 3. The sample file tells tox to run the tests in python 2.7 and python 3.4. Modify this line to test the python versions you would like to include. -The rest of the code tells tox what it's doing, the first assignment, +The rest of the code tells tox what it's doing. The first assignment, `passenv` informs tox that it will (eventually) be run on the [Travis CI](https://travis-ci.org/) server for continuous integration. We will discuss how to setup up Travis in a [later section](../README.md#continuous-integration-code-coverage-and-quality). The next assignment, `deps` tells tox which packages it will need to run -your tests, in this case we've listed pytest (which actually runs the -tests), coverage (which makes code coverage reports [discussed -later](../README.md#continuous-integration-code-coverage-and-quality)), -and codecov (which also handles coverage reports). Finally we use -`commands` to tell tox what it's doing, the command we supply it with +your tests. In this case we've listed: + + - pytest (which actually runs the tests) + - coverage (which makes code coverage reports [discussed later](../README.md#continuous-integration-code-coverage-and-quality)) + - codecov (which also handles coverage reports) + +Finally we use `commands` to tell tox what it's doing, the command we supply it with is `coverage run --source=my_pkg -m pytest` (replace my_pkg with your package name). This tells tox to use the command `coverage run` on your package (`--source=my_pkg`), with the method pytest (`-m -pytest`). You can use tox.ini to do a lot of other things as well, if -your interested read the -[documentation](http://tox.readthedocs.io/en/latest/examples.html), -but in most cases what you see here is all you will need. +pytest`). You can use tox.ini to do a lot of other things as well--if +you're interested read the +[documentation](http://tox.readthedocs.io/en/latest/examples.html)--but +in most cases what you see here is all you will need. -At this point your repository folder should look like: +At this point your repository folder should look like this: ``` 'my_repo'/'package'/__init__.py @@ -205,7 +206,7 @@ At this point your repository folder should look like: ``` Now we're going to copy your repository to the docker container to run -the test and make sure that they work (just like you did when testing +the tests and make sure that they work (just like you did when testing your [python package setup](python_packages.md#testing-your-package)): ``` @@ -222,8 +223,8 @@ cd 'my_repo' tox ``` -A bunch of stuff should print to your screen at the end of which you -should see something like: +A bunch of stuff should print to your screen, but we'll just focus on +the last bit which should say something like this: ``` ____________________________________________________________ summary _____________________________________________________________ @@ -232,8 +233,9 @@ ____________________________________________________________ summary ___________ congratulations :) ``` -But with py27 and py34 replaced with the python versions you chose to -test on. If you see any errors at this point please double check +Note that since we tested using python 2.4 and python 3.7, the output +listed py27 and py34. If you tested different versions of python your code +should reflect that. If you see any errors at this point, please double check everything you've done in this section and try again. If it still won't work please submit an [issue](https://github.com/msg-byu/getting-started/issues) describing @@ -251,7 +253,7 @@ second function inside of trial.py using the test-driven framework. ### Your Second Function -Inside of trial.py start a new function called factorial: +Inside of trial.py define a new function called factorial: ``` def factorial(n): @@ -262,7 +264,7 @@ factorial of an integer. Let's write the documentation for our new function: ``` - """Factorial calculates the factorial of the provided integer. + """Calculates the factorial of the provided integer. Args: n (int): The value that the factorial will be computed from. @@ -275,14 +277,14 @@ new function: """ ``` -We've included a raises descriptor in the documentation since if the -user tries to pass 'factorial' a float (say 3.5) we want to warn them -of the error rather than try to find the factorial. Now before we +We've included a raises descriptor in the documentation, since if the +user tries to pass a float (say 3.5) into the function, we want to warn them +of the error rather than try to find the factorial. Now, before we write a single line of code let's write some unit tests. Inside of tests/test_my_pkg.py add the following lines of code for -tests, you can add additional tests if you so desire but make sure you -have at least these ones: +tests. You can add additional tests if you so desire, but make sure you +at least have these ones: ``` def test_factorial(): @@ -384,10 +386,10 @@ With: ``` Now if the input value isn't an integer, we check to see if the input -value is equivalent to an integer. If it is, we replace it with -one. With that fixed, let's check to see if we're passing all our tests -again in the docker container. (Don't forget to copy the code you've -changed into the container before running `tox`). +value is equivalent to an integer. If it is, we replace it with the +equivalent integer. With that fixed, let's check to see if we're +passing all our tests again in the docker container. (Don't forget +to copy the code you've changed into the container before running `tox`). The result should be something like: @@ -425,7 +427,7 @@ of 1. We'll need to fix this as well so in your code replace: With: ``` - if n =< 0: + if n <= 0: fact = 1 ``` @@ -443,7 +445,7 @@ ____________________________________________________________ summary ___________ Just to be clear, the work flow in test-driven development is to decide what your code should do and write tests to verify -that performance before you write any code. In other words each time +that performance before you write any code. In other words, each time you start to write a new function you should (1) define the function, (2) write its documentation, (3) write tests to model the desired output, and only then (4) write the code. This will ensure that all your functions have unit diff --git a/instructions/github.md b/instructions/github.md index d341ea5..42c2b53 100644 --- a/instructions/github.md +++ b/instructions/github.md @@ -17,14 +17,14 @@ code that is being developed. It makes it easy to share code with people around the world. Most, if not all, of the code you write as part of this group will be maintained on GitHub so learning git will be an important in your development. You will use git in the terminal -to interact with GitHub one you are setup. +to interact with GitHub once you are setup. ## Create a Repository To make a GitHub account go to [GitHub](https://github.com/), click sign up for GitHub, and create your user name and password. Once you have logged into GitHub, create a new repository by clicking on the -plus sign on the top right of the window and clicking on 'Now repository' +plus sign on the top right of the window and clicking on 'New repository' from the drop-down menu. You now need to give the repository a name. You can give it any name you’d like, but I would recommend titling it something related to the exercise you've been given by Dr. Hart. You @@ -50,8 +50,8 @@ create for the exercise you have been assigned. GitHub not only hosts your code but it will allow you to maintain multiple versions of your code at the same time. This is extremely useful when trying to maintain a working and stable code system. For -example lets say you, or someone you collaborate with, are working on -adding new functionality to a code you wrote but accidently introduced +example let's say you, or someone you collaborate with, are working on +adding new functionality to a code you wrote but accidentally introduced a bug into the code. If you push, git's way of updating the repository in the server, to the live code copy then anyone who tries to use the code will experience the bug. That is why it is always a good idea to @@ -62,7 +62,7 @@ to merge the changes into your main repository. To help you get into the habit of working on a development branch let's create one for your new repository. On the repository home page -you should see a button labeled `Branch: master`. Click on it and in +you should see a button labeled `Branch: main`. Click on it and in the text field type the word 'dev'. You should then see new box show up saying `Create branch dev`. Click on it. You have now created a development branch to work in. @@ -73,8 +73,8 @@ We will now copy this repository to your local machine so you can add to it. Open your terminal, or command prompt/[Cygwin](https://www.cygwin.com/) for windows, and use the `cd` command to move to a place on your system that you want to store your -code (I would recommend making a separate directory for all your codes -called codes). (If you don't know what the `cd` command means, click [here](https://github.com/yeward97/getting-started/blob/patch-2/instructions/UNIX.md) for a quick crash course.) +code (I would recommend making a separate directory called codes for +all your codes). (If you don't know what the `cd` command means, click [here](https://github.com/yeward97/getting-started/blob/patch-2/instructions/UNIX.md) for a quick crash course.) Once you are in the desired location click the green 'Clone or download' button and copy the address it shows you. Then in the @@ -105,7 +105,7 @@ git checkout dev ``` We are now working on the dev branch and anything we commit will be -pushed to dev instead of master creating a stable code base. +pushed to dev instead of main creating a stable code base. -You are now ready to return to the remainder of the walkthrogh found +You are now ready to return to the remainder of the walkthrough found [here](../README.md#python). diff --git a/instructions/python_packages.md b/instructions/python_packages.md index 62f29ba..d30f831 100644 --- a/instructions/python_packages.md +++ b/instructions/python_packages.md @@ -20,7 +20,7 @@ pip install numpy ``` in your docker terminal. This simple command installs the python -package called numpy which contains almost every numerical tool you +package called numpy, which contains almost every numerical tool you will ever need when you program. You can now access the numpy tools simply by using: @@ -30,9 +30,9 @@ import numpy in any of your python scripts. Numpy, and many other packages, are available for anyone to use anywhere through the [python package -index](https://pypi.python.org/pypi) (pypi). In this walk through we +index](https://pypi.python.org/pypi) (pypi). In this walkthrough we will not be adding your package to the index, but if you build a code -that you feel should be on the index then do so, instructions on how +that you think should be on the index then do so, instructions on how to do that can be found [here](http://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/contributing.html). @@ -44,7 +44,7 @@ package name and create a folder in your repository with that name. This folder will contain all your python code for this project. By convention, python package names are usually lower case without spaces. You don't have to follow these conventions, but it is a -good idea to keep them in mind in case you do submit a your package to +good idea to keep them in mind in case you do submit a package to pypi. In the [sample repository](https://github.com/msg-byu/getting-started) the package name is `my_pkg` so the command would be: @@ -58,10 +58,10 @@ to create a [setup.py](../setup.py) and [setup.cfg](../setup.cfg). These files tell `pip` how to install your package. You will find templates of both files in the sample repository. You should copy them to your repository so that they are -on the same level as you package directory. You will also want to make -a file `__init__.py` in the package folder, this file will remain -empty during this walk through but it can be used to do some useful -things shorten user imports or import tools for the entire +on the same level as your package directory. You will also want to make +a file `__init__.py` in the package folder. This file will remain +empty during this walkthrough, but it can do some useful +things like shorten user imports or import tools for the entire package. Examples of this can be found [here](https://github.com/wsmorgan/analyzefit/blob/master/analyzefit/__init__.py). @@ -105,8 +105,8 @@ Here you enter the current distribution version of your code. The distribution version takes the form of a period separated list with entries of major revision, minor revision, and patch revisions. A major revision occurs when you change how your code works, that is if -someone was using your code before the revision for a project and -attempted to use it the same way afterwards the code would no longer +someone was using your code for a project before the revision and +attempted to use it the same way afterwards, the code would no longer function. A minor revision is a change in the public API, such as creating a new subroutine or function that is publicly available. The patch revisions are small changes to the code to fix issues and @@ -160,7 +160,7 @@ install_requires = [ You don't need to change anything here yet but you should be aware of this field. As you build your code you may find yourself making use of -other python packages such as numpy or matplotlib (pythons plotting +other python packages such as numpy or matplotlib (python's plotting package). Any packages your code needs in order to install and run properly should be listed here as a comma separated list and usually with each entry on a separate line. For example if matplotlib is being @@ -191,7 +191,7 @@ This is another field that you can ignore for now but should be aware of. Any scripts, i.e., command line executable programs, you place in these brackets will get copied to your bin (the place on your computer where anything you can type into the terminal, like 'cp', lives). Only -ever uncomment this line if you have a script to install, otherwise +uncomment this line if you have a script to install, otherwise setup.py will fail. ``` @@ -289,12 +289,12 @@ def square(x): ``` Here we have defined a function that squares a given value. The text -inside of three quotes in this functions is +inside of triple quotes in this function is [documentation](../README.md#your-first-code) which we go into in more detail later. Now that we have some code to test with we can install our package and -insure that it functions properly. First we need to copy all our code +ensure that it functions properly. First we need to copy all our code to our docker container. To do this you need your docker container running in one terminal while you use another to copy files to it. If your docker container is not running then use: @@ -303,7 +303,7 @@ your docker container is not running then use: docker run --name my_container --rm -i -t wsmorgan/python bash ``` -to get it going. Then in your other terminal use navigate to the +to get it going. Then in your other terminal navigate to the folder your git repository is in and use: ``` @@ -325,7 +325,7 @@ exit() ``` You should have seen the number 4 printed to the screen before you -typed `exit()`. If you didn't or any of these commands gave you errors +typed `exit()`. If you didn't, or if any of these commands gave you errors, stop and go back through this setup to ensure that you have everything correct. If @@ -343,9 +343,11 @@ here](https://github.com/msg-byu/getting-started/issues) describing your problem and we'll get back to you ASAP. What you just did is install a local copy of your package. You only -need to do this once per package because the code python is importing -is now the live version of your code on your machine. Any changes you -make will effect the output immediately. +need to do this once per package because when you import this code into +your docker container, you now have a live copy of your code on your machine. +Any changes you make to the code will affect the output immediately. +Just remember that if you want to keep those changes, you will need to push them +to your github repository. You have now successfully created your first python package. Please return to the main [walk through](../README.md#your-first-code).