Code for Thought¶

Requirements¶

First and foremost we recommend and assume a POSIX based environment. This means either a Linux operating system, like Xubuntu (which could be installed as a virtual machine using VirtualBox in any operating system) or on windows you could install Cygwin (an easy way to get a POSIX based environment in windows for a few trade offs). All instructions in this book are given as command line commands for a POSIX environment. There may be equivalents for your own setup that can be found on the internet with a cursory google search.

There are many many guides on the internet on how to setup these environments, many of which explain it all better then I could in the limited scope of this book.

Ontop of some kind of POSIX based environment you are going to need to install Python along with the packages called Setuptools and Pip. Python will be the language we will be learning how to code in. It is a very nice to read and concise language that is perfect for beginners learning the basic concepts of programming. Setuptools and Pip will help us to install and distribute Python packages.

In these environments there should be some kind of text/code editor you are comfortable with using. Anything will do and you can change your mind and use something else at any point. Personally I use Emacs which is a great editor that has a long tradition in the programming world, although people say it has a steep learning curve. Most programmers prefer Vim to Emacs but there are many alternatives and if it comes down to it windows notepad will work fine... However if you want to use notepad give NotepadPlusPlus a try. It is similar to notepad but with useful programming features.

This can all be done in pure windows obviously however programming in Linux is just much nicer. If you wish to program in windows only (without Cygwin) you will still need a text editor and be able to use the command prompt to run your code. There may be mention of tools that are different to use or nonexistent on windows. Most likely in these cases there are alternatives that should not be too hard to find with a quick Google.

If you do not want to deal with the recommended environment outlined above you can follow much of this book using the REPL website which offers a half decent python interpreter right in your browser. Much of the code examples in this book are written in Python because it is a clear, and easy to follow, programming language that follows many of the universal programming concepts and REPL offers a great solution without making any changes to your computer. The website offers a Python 2.7 interpreter and a nice clean text editor on the side that can interact with the interpreter all inside your browser. However later chapters in this book will fall out of the scope of the REPL website.

Structure¶

Code for Thought will take you through learning how to write your own code from start to finish. By the end of this you will understand the major concepts behind programming and the tools that will make your code more successful. You will learn how to test your code and make sure it works, how to document it so that others can help contribute to your code, and learn how to contribute to other peoples code and make the world a better place.

OK. maybe you won’t be influencing the entire world by the end of this book but today, more than ever, the world needs people who can program. Almost everyone you know uses computers far more then they would have 15, 10, even 5 years ago. Yet we are all just users, so few care to even think what is behind it all. Truth is that in general it is simpler than you think. If more people can innovate and contribute to the growing world of computers then that has to be making the world at least a little better, right?

This book will move slowly from concept to concept, focusing not just on teaching you some information about programming but actually teaching you how to teach yourself to program.

We start with an introduction to the basic concepts of programming with interactive examples. Then we move onto abstracting ideas into functions. Then on to data structures. With these basics we will begin to construct simple programs you can test out and tinker with. Then we will use example programs and code to provide real life usage of the advanced concepts you will be learning. As the projects we work with grow in size we will introduce new tools that can greatly help with programming. These include, but are not limited to, things like; version control, unit-testing and documentation.

At the end we will have a more free form discussion (albeit rather one sided) about programming concepts and tools for the future.

Dedication¶

This book is dedicated to, Elysha. Code for Thought is designed to help her and others like her to learn code and better understand the second love of my life.

New kid on the block¶

This is our stomping ground so we need to learn how to start stomping to get results!

The first piece of programming we will be learning is a simple expression. Expressions are chunks of code that do something and return results.

There are a great many things you can do with expressions but for now lets just try some simple math in our Python Interpreter:

>>> 1 + 2
3
>>> 1 / 2.0 * 20
10.0
>>> 1 / (2.0 * 20)
0.025

Great so we have written some simple, but boring, mathematical expressions in Python! But the last two examples are a bit different. First, if you didn’t guess already, the symbol for multiplication in programming is the asterisk (*) character and division is the forward slash (/) character. But the last two examples are almost exactly the same except for the parenthesis around the 2.0 * 20 expression in the final one.

The reason for the parenthesis is to solve one of the largest problems in programming. OK well not specifically but bare with me for a moment. One of the largest problems for new programmers, other than the syntax of the language they have chosen, is understanding that the computer does not (and can not) think the way they do. It has no clue what you want to do with your code. This makes it very hard for a computer to figure out what the right thing to do is, so often it doesn’t even try.

In programming we need to make our intentions clear and preferably concise. Not only does a computer have to understand what you mean but so do other humans. This speaks to a balance that we need to find between telling the computer exactly what to do to get it right, and being able to actually articulate, and understand those commands ourselves. Remember that while you may understand what you write today if you come back in six months will it still make perfect sense?

But we are getting ahead of ourselves a bit. We use the parenthesis in the last example above because we want to divide 1 by the result of 2.0 multiplied by 20. Whereas in the second example we are dividing 1 by 2.0 and then multiplying the result of that by 20.

Can I have a locker next to yours?¶

So we have some basic numbers and we can manipulate these numbers. What we need to do now is store them. In programming we use variables to store information under a (sometimes) easy to remember name. Instead of just saying 100 we can store that number in a variable called distance to more easily remember what the number does and what it means. Languages have many different ways to create and interact with variables. Luckily Python is a dynamic language (more on that in the future) and we can just give any value a name really simply:

>>> distance = 100
>>> distance
100

Now that we have stored the speed variable we can use it in calculations instead of the number and store the result.

>>> speed = distance / 20.0
>>> speed
5.0

The above is just a simple velocity calculation (I promise we will move away from maths soon) that uses the stored distance variable we set earlier and divides it by 20.0 (the time it took for our imaginary vehicle to travel that distance) and then stored the result in the variable called speed.

The important thing here is not the maths, it is the fact that you can store almost anything to a variable and use the variable instead of the actual value. Now that distance is stored in a variable all we have to do is change the distance value to something else and re-run the speed calculation and it will use the new distance! OK not that exciting yet. But it will be.

He’s Just Not My Type¶

There are more things than numbers in the world of programming. And there is much more than maths. Actually only very few programming fields are math heavy. Mostly we deal with basic data types and manipulating them to become what we want.

Generally speaking, there are only a few basic types of data we can use and store.

>>> name = "Taylor \"Nekroze\" Lawson"

>>> name = 'Taylor "Nekroze" Lawson'

>>> shades = ['white', 'black']
>>> shades.append('grey')
>>> shades
['white', 'black', 'grey']

>>> favorite = {'color': 'black', 'language': 'Python'}
>>> favorite['color']
'black'

I Love it When a Plan Comes Together¶

Using just the types of data above and learning how to manipulate them we can make just about any piece of software we can imagine. No, really. Pretty much every computer program ever written uses some form of the above data types along with a series of tricks to manipulate and control them. It’s kind of beautiful if you think about it. Ever single computer in the world; phones, laptops, airplanes, traffic lights. At some level these are all controlled by code that just fiddles with these basic types. This is why coding is such a powerful field, everything uses it somewhere.

The goal is for you to learn how programming works, not just Python. Play around with these data types in the Python Interpreter to get a better feel for how they work, because these things are almost entirely universal in programming. And once you get the basic concepts behind programming itself, the language you use becomes a trivial wrapper around your thoughts. Now that is what Code for Thought is all about!

In the next chapter we will be looking at using functions and telling the computer how to do a repetitive tasks.

What is your quest?¶

Say we wanted to do a calculation. Say we wanted to do a calculation often. It would be useful (increasingly so with added complexity) to separate the calculation into a function.

Functions are sets of instructions that are executed whenever the function is called by name and can optionally take in data and even provide an output.

Imagine we had a reason to count how many times the letter “a” is in a given string and return the result. Instead of writing the instructions required to perform this task each time it is needed we could write a function that does it for us. For example in python we would do the following:

>>> def count_a(text):
...     count = 0
...     for letter in text:
...         if letter == "a":
...             count += 1
...     return count
>>> count_a("A test sample")
1

The above code presents a host of new programming features that will be covered in this section.

Firstly we defined a function called count_a and told it to take one parameter called text. This parameter is our input that we will count.

In programming we have the concept of code blocks, these are a section of code that belongs to some other code. Some languages use braces such as {} to say that anything in between those symbols is a code block. However Python uses white space indentation do denote a code block. This means that anything on the same indentation level is part of that code block and further indentations denote nested code blocks. After defining our count_a function we need to give it a block of code that defines what that function will do when it is called latter. Code blocks are used whenever we need to define what a specific thing should do when it is called; the code of a function, what to do in a loop, code to execute if a condition is met, etc.

The next line should be rather familiar by now. We are simply creating a integer variable to store the count, which starts at zero.

Here is where things get interesting, control flow. We need to check over each letter in the text variable and see if it is the letter we are looking for. To accomplish this we have employed a for loop. For loops are very common in programming however some languages have different types of for loops. In python the for loop is more of a foreach loop, unfortunately it is not named as such. Basically it takes any iterable value (more on that later but for now its anything that can be looped over) and gives you each piece of that value until there are no more pieces left. Here we have given the for loop the text value and told it to call each piece of it letter.

Next we introduce another new type of control flow called the if statement. An if statement evaluates a boolean expression and then allows you to execute instructions if it is true. The boolean expression we are using here is letter == "a". Meaning if the piece of the text parameter we are looking at currently is the same as a string containing the letter a then the boolean expression evaluates to true. The if statement, now having an expression that equals true then executes its code. In this case that is to add 1 to the count variable.

When adding one to the count variable we are using the in place addition operator += because we want to store the result in the same place. we could instead use the following:

count = count + 1

this would do the calculation of whatever is stored in the count variable plus one and then store it into the count variable. This does the exact same thing but is a little longer. However we could not just say count + 1 and thats it because that is an expression and that expression will return the sum of count plus one but has no idea that it needs to be stored.

After the if statement the for loop will return to the top and get the next letter from text and do it all again until we have gotten to the end of the input.

Once all letters have been checked the count variable will now be storing the exact amount of the letter a that are contained within the text that this function is given. But its of no use to just count the letters and then forget about it so we need to return the results using, you guessed it, return count. By now it should be rather obvious that this will simply return whatever is stored in the variable count back out to whatever has called this function.

Finally we see our brand new function in action by calling count_a("A test sample") return the result 1. In our function we only checked for the letter a but we must remember that this is not the same as A as strings are case sensitive. If we wanted to check for both lowercase and uppercase a we could change the boolean expression for the if statement to a little to the following:

letter == "a" or letter == "A"

Then the if statement has two boolean expressions that make up the larger boolean expression. Firstly it checks for the lowercase a then if that is false it will continue to the uppercase A check and if that is also false then the entire boolean expression will be false and not execute the if statements instructions. In python you can also use the and keyword if both of these boolean expressions needed to be true in order to proceed. In this case however the and keyword would do no good because a letter cannot be lowercase and uppercase at the same time so we use or.

Go with the flow man¶

In programming we often use control flow statements to alter the way our code performs.

>>> def message(code):
...     if code == 1:
...         print("Hello world!")
...     elif code == 2:
...         print("Goodbye cruel world!")
...     else:
...         print("I don't even know what to say...")
...     return True
>>> message(1)
Hello world!
True
>>> message(2)
Goodbye cruel world!
True
>>> message(3)
I don't even know what to say...
True

for (int count; count >= 10; count++){
    dosomething();
}

>>> friends = ["nekroze", "lyshkah"]
>>> for name in friends:
...     print(name)
nekroze
lyshkah

>>> loops = 0
>>> while loops < 10:
...     loops += 1
>>> loops
10

The Layer Cake¶

Another very useful feature of OOP is Inheritance. What this means is that one object definition can be based on another, taking all its variables and methods and building on top of them.

Lets just go straight to an example this time.

>>> class InSpace(object):
...     def __init__(self, posx=0, posy=0, posz=0):
...         self.posx = posx
...         self.posy = posy
...         self.posz = posz
>>> class Cube(InSpace):
...     def __init__(self, size, posx=0, posy=0, posz=0):
...         super(Cube, self).__init__(posx, posy, posz)
...         self.size = size
>>> destination = InSpace(1,posz=5)
>>> destination.posx
1
>>> destination.posy
0
>>> companion = Cube(10)
>>> companion.posx
0

This time we are doing things a little different.

We start off with similar thing to before, we are just creating a new class to define things that exist in a three dimensional space. However here we are using default arguments to allow the constructor to optionally take the position of an InSpace object only if it is given, otherwise that dimension will be 0.

Next we define a new Cube object, this time instead of inheriting directly from object we inherit from InSpace. This means that our new object will have everything that InSpace has and can be used anywhere an InSpace object is expected. For this objects constructor we tell it that we want the size argument to be required and have the position arguments to default to 0 upon creation/initialization of this object.

In some languages, Python included, you will need to explicitly call the constructor of the “parent” object if you want it to be executed. Python uses the super function to make this a bit easier in Python 3 it is even easier as super can be called with no arguments to do exactly the same thing as above, but people are still using both so I show what works everywhere.

This is more language specific rather then general programming and so is not something I will go into too deeply. Suffice to say that above we use super to get the object definition of the parent of Cube and then call its constructor appropriately.

After we have defined our object hierarchy I have just done some example usages of both classes including different ways to use the optional positional arguments.

The Method to my Madness¶

Now we can go about doing cooler things like giving special methods that only cubes can use or even better adding methods to InSpace that allows every object definition that inherits it to easily move around without having to update its “children” such as Cube. In fact lets do just that!

Using the above example, again, any changes in the code to the InSpace class will be reflected in any class that inherits from it (it’s children) accordingly. Because of this we can easily abstract the concepts behind a class in its base components. So if everything exists in a three dimensional space it might be a good idea to implement things specific to being in such a space in a class such as InSpace so each object that derives from it does not have to implement such things over and over again. This leaves each object inheriting from InSpace to focus on what it specifically needs to accomplish it’s job.

With this in mind let us redefine the InSpace class with some methods to help us move around in a space.

class InSpace(object):
    def __init__(self, posx=0, posy=0, posz=0):
        self.posx = posx
        self.posy = posy
        self.posz = posz

    def move_x(self, distance):
        self.posx += distance

    def move_y(self, distance):
        self.posy += distance

    def move_z(self, distance):
        self.posz += distance

With this as our new base class we can use the move_ methods from any object that inherits from InSpace.

This means that we can use the Cube class as it was defined above and do companion.move_x(10) to move 10 units forward in space and companion.move_x(-10) to move 10 units backwards. Note that in the function call to move backwards we use -10 for a specific reason.

We could have a method for moving forwards and backwards on each axis but that may get a little messy. Instead we use a more general approach. When we add the distance to a variable we use the += operator which adds distance to the current value of the variable on the left and then stores the result in the same place. Basically the final two statements are identical.

>>> position = 0
>>> position = position + 10
>>> position += 10

Now comes the part that we abuse to make the movement three simple methods instead of six. When you add a negative number (-10 in our case) to another number it will actually perform a minus operation. By using this we can just hand the move methods positive numbers when we want to move forward on that axis and a negative integer when we want to move backwards. Neat huh!

This Isn’t Even my Final Form¶

It doesn’t end here. Depending on you needs and what you language of choice provides you can create powerful base classes and object hierarchies or even interfaces that you can use to make your code easily re-usable and even extendable.

Some languages allow a class to inherit from multiple classes at once. In statically typed languages there is often Templating which allows for you to make a generic class that can be used with any object type. There are very few problems that cannot be solved using an OOP approach.

It sounds complex but this can be super helpful. However just the basics outlined here is more then enough to get you into the world of OOP and open up a lot of possibilities for better code.

Pass the Source¶

Obviously if we split our code into different files we will need a method of telling one file that it uses something in another file. Today this is usually called “importing” (sometimes called include) and is often written at the top of a source file. Importing is used not just to reference your own code in other files but other code that is included in your programming language of choice, or even a library that someone else wrote that you wish to use.

In Python we can write the following code which will calculate 2 to the power of 10 using the math module that comes with Python.

>>> import math
>>> math.pow(2, 10)
1024.0

By using the import keyword we have told the language (Python in this case) that it should look for a module named math so that we can use the code defined in math.

When you ask to import something the language will go looking in some predefined locations that it thinks the source code is likely to be. Usually it will first look in the current directory that you or your root source file is located in. Then it might search other locations that it thinks its libraries will be installed to. This means that even though Python comes with a math module, if I wrote another Python file in the same directory that I started the python command line interpreter then that file would be imported instead. This is because it looks there before looking in the libraries included by Python.

Most languages work in a very similar way. Some languages have Imports (or includes) that work slightly differently or can be made more specific. In C/C++ when another file is included then everything in that file is brought into the current file as if it where written here. Meaning if there is a function called pow in the file we are including and we also have one in the source file after the include then it will override the previous pow.

A similar thing can be done in Python but it is not recommended for exactly the reason I mentioned above. It pollutes your source code by importing everything into the current Namespace.

>>> from math import *
>>> pow(2, 10)
1024.0

While this is generally considered a bad thing to do in many modern programming circles it does present something nice. We do not have to prefix any math usage with its Namespace, we just call the pow function directly. This may sound like a trade off that needs to be considered but many languages have already beaten you to a beautiful solution, selective imports!.

If all we are going to do is use the pow function, and it is not going to cause any confusion or conflicts with other code in our own module, why not just import pow and nothing else. Seems logical, lets do that.

>>> from math import pow
>>> pow(2, 10)
1024.0

There we have it. We are now importing only what we use. There are arguments for both this method and just importing only the math module, Namespace and all, however they are a little beyond this book. No one here is trying to tell you how anything has to be done. But, I do encourage you to experiment and decide what is best for your self.

As a final note on importing things in cool ways. What if we do only want to import a specific function, or even then whole module, but we already have something that has the same name in our current module that would cause conflicts. A few languages will allow you to rename what you import, Python included.

>>> from math import pow as mathpow
>>> mathpow(2, 10)
1024.0
>>> import math as realmath
>>> realmath.pow(2, 10)
1024.0

Using these two methods we can usually dance around any import conflicts and land on some beautiful code.

Although when importing modules do be careful about “Circular Dependencies”. If module A imports module B which imports module A, this can be a real problem and some languages will just fail to handle this at all if you are lucky. If you are unlucky they may get stuck in a loop or not give you any hint as to why it is failing.

Fair Shake of the Source¶

Some languages do not have an interactive interpreter and must be used by compiling/interpreting source files. In Python we can do both.

Source files are plain text files that use a specific file extension (the last few letters of a file name after a dot, ie. filename.txt the extension is .txt) that can be edited using anything that can write a simple text file although some editors have better support for programming.

We could start an entire war over which editor is the best to use, we covered some of the common choices in the Introduction and left it to you to research and decide what you like the best. Experiment away, that’s what we are here to do.

Another important thing about source files is that they usually have some kind of entry point. An entry point is usually a function called main that is the start of our programs execution.

Python is a little different but every language has its twists. We are going to write a simple program that will just say Hello World! to the user. This is a pretty program that is very often used as a first tutorial or introduction to a specific programming language.

Source files for Python are denoted by the .py file extension. So here is greeting.py

def greeter():
    print("Hello World!")

if __name__ == "__main__":
    greeter()

Now if we run python greeting.py from the command line we will get our greeting. Finally we touched on something where Python may not be the easiest language to demonstrate with. I will give a little explanation.

In most languages there is just some kind of main function or equivalent entry point. Due to the nature of Python we need to jump through a few hoops to do the same thing.

We could get the same results if we wrote the file like this.

def greeter():
    print("Hello World!")
greeter()

Or, for those of you who are a little sharper, you may have noticed we can just make this a one line file and do the same thing still.

print("Hello World!")

However we do not do this when we are writing a program. As a single file script this works just fine but what if some other source files in our program wanted to use greeting.py. Give it a go and see what happens. If we change the greeting.py source code to either of the previous two examples and then open a new Python interpreter with python on the command line in the same directory as the greeting.py source file.

If we entered import greeting it would print out Hello World! which in the second examples case means that just by importing the module the greeter function was called. However the first example will only call the function when that source is the file being executed by python directly as we did by calling python greeting.py making the greeting module have the special __name__ variable equal "__main__".

In this case it does not really matter if you understand why this happens just that you know that with python that is how it is done.

If you are still having problems figuring out when to use which method just take a moment to experiment. After all experimenting is the best way to learn programming (in my opinion) and is a core concept of this book.

Packages¶

After all this we now have a greeting module but what if we want to step up the complexity. This is where packages come in. When there are lots of source files it can be easier to sort things into a hierarchy of directories. For example in a game we might want to have a package for everything to do with drawing to the screen and a different package for all the networking code. So what we can do is have a directory structure that looks like this:

./
./game.py
./graphics/
./graphics/screen.py
./network/
./network/client.py

With this directory structure graphics and network are packages that contain the screen and client modules (respectively) and as such we can use these modules by saying from graphics import screen or with Python and some other languages we can even get something specific from our modules:

from graphics.screen import draw

It is worth noting that the example file structure given above will not work in Python because it wont just accept any directory as a package. In Python a directory that should be considered a package must have a file in it called __init__.py that can be empty. This file is what is executed when you import just the package, for example import graphics would run any code in __init__.py before continuing. This is specific to python but the general package concept holds true even for languages that don’t support modern “packages”. For example in C/C++ instead of giving the package/module names you give the file path:

#include "graphics/screen.h"

Using packages can make code maintenance much easier and the entire project easier to understand.

This Title Explains the Content of This Sub-Chapter¶

Not all programming languages agree on a common method of denoting a comment but usually it is just a special character and then the rest of the line is ignored by the programming language. This means anything after that special character can only be seen by viewing the source code, sounds like the perfect place to explain things.

Programmers are lazy folk, we do not want to remember everything about our code and usually we can’t. So what we often do is use a comment to describe what some code does, especially when it isn’t readily apparent what the code really does.

Lets write some comments for our old 3d space example.

class InSpace(object):

    def __init__(self, posx=0, posy=0, posz=0):
        self.posx = posx
        self.posy = posy
        self.posz = posz

    def move_x(self, distance):
        self.posx += distance #Add distance to position x

    def move_y(self, distance):
        self.posy += distance #Add distance to position y

    def move_z(self, distance):
        self.posz += distance #Add distance to position z

class Cube(InSpace):

    def __init__(self, size, posx=0, posy=0, posz=0):
        #Call the parent constructor.
        super(Cube, self).__init__(posx, posy, posz)
        self.size = size

Our code functions the same but we have now added some comments to explain what is going on in some of the less obvious areas. In Python comments are started with the pound (#) character. Some languages us a double forward slash (//) for single line comments and forward slash asterisk (/*) to denote the start of a multi-line comment and the opposite to end that comment (*/). While pound only does single line comments in Python that does not mean that we are missing out. There is wisdom in the way Python does things, instead of providing multi-line comments it provides what it calls “doc strings” which are actually multi-line comments however they are also documentation that can be accessed by the user of your code and they look like strings. That’s probably why they are called “doc strings”.

Unlike Humans, Chuck Norris Doesn’t Need Documentation¶

When learning how to use a piece of software one of the most useful things that it can provide is clear, up to date, documentation. Lets go straight to writing some documentation.

In Python we can use a “doc string” to document a piece of code like a class, a function, or a method.

Lets add some documentation to our 3d space code.

class InSpace(object):
    """
    Describes an object in a 3d environment.
    """
    def __init__(self, posx=0, posy=0, posz=0):
        self.posx = posx
        self.posy = posy
        self.posz = posz

    def move_x(self, distance):
        """Move on the X axis."""
        self.posx += distance #Add distance to position x

    def move_y(self, distance):
        """Move on the Y axis."""
        self.posy += distance #Add distance to position y

    def move_z(self, distance):
        """Move on the Z axis."""
        self.posz += distance #Add distance to position z

class Cube(InSpace):
    """
    A Cube in 3d space.

    Stores a single size variable for the size of all edges.
    """
    def __init__(self, size, posx=0, posy=0, posz=0):
        #Call the parent constructor.
        super(Cube, self).__init__(posx, posy, posz)
        self.size = size

Python has a handy help function that can output doc strings for anything that is given to it. This is the basis of documentation in Python and can be used in more complex ways in the future. For example, tools can be used that get all of the doc strings in your code and turn them into a website, or file, that can be shared with the world.

For now give this example a go. Put the new documented 3d space classes into a file and try using the help function to view the documentation.

Types of Contributions¶

Get Started!¶

Ready to contribute? Here’s how to set up codeforthought for local development.

1. Fork the codeforthought repo on GitHub.

2. Clone your fork locally:

   $ git clone git@github.com:your_name_here/codeforthought.git
   

3. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature
   

   Now you can make your changes locally.

4. When you’re done making changes, check that your changes pass all the tests. You can use either the following command to do all tests at once:

   $ make test
   

   Or seperately:

   1. Test web links:

      $ make linkcheck
      

   2. Test doctests and code examples:

      $ make doctest
      

   3. Test html building:

      $ make html
      

5. Commit your changes and push your branch to GitHub:

   $ git add --all .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature
   

6. Submit a pull request through the GitHub website.