1. Documentation & testing in practice
Our last step is to look at documentation and testing in the wild. We'll cover some useful tools and their benefits. We won't go into detail on how to implement everything, but there's a lot of good documentation online for the tools that we'll cover. Also, these tools won't be available in the course exercises for practice.
2. Documenting projects with Sphinx
Sphinx was mentioned earlier as a tool that transforms docstrings into beautiful documentation. Here we see an example of what your Document class might look like as an HTML page generated by Sphinx.
All of this benefit just from writing complete docstrings!
If you're managing your project with GitHub or GitLab then you can even host your Sphinx-built documentation for free using the products' services. That way users can search the web to find your helpful documentation.
3. Documenting classes
You might have noticed that the example Sphinx page showed documentation for a class and included information on attributes. Let's take a quick aside to look at the docstring that was used to build the page.
This docstring should look mostly familiar, but here are a couple of things to note.
We document the parameters for the init method in the class docstring. This way users can see how to initialize a new instance by calling help on the class itself.
Next, we document attributes using the 'ivar' keyword. This abbreviation stands for 'instance variable'. With this documentation in place, users can easily see how to use your class.
4. Continuous integration testing
By using pytest extensively you'll be able to have most, if not all, of your project's code being tested, but it can be a bit of a bother to have to always run the tests repeatedly from the command line.
This is where tools like Travis CI come in. The CI stands for continuous integration, and it just means that you are continually adding new code to your project. When adding this new code, Travis can automatically run your tests for you and alert you if your changes broke something.
5. Continuous integration testing
Then when you push a fix, Travis CI will run your tests again to double check that your fix was successful.
Another great aspect of Travis CI and other CI testing tools is scheduled builds. By scheduling a build your tests can be run periodically even without you adding new code. Scheduled tests are a great way to catch bugs introduced by updates in one of your dependencies.
6. Links and additional tools
To close out, let's list out some links for the tools we've covered and some additional ones.
First, here are links to the tools we just covered.
Next, GitHub and GitLab are great for storing open source projects. They are based on the tool, 'git'. To learn more about git you can check out the related DataCamp course.
Codecov is a tool that lets you explore which parts of your code are being tested by your automatic tests; this is known as test coverage. By keeping your project's test coverage high you will be less prone to surprise bugs.
Code Climate is a tool that will analyze your code's readability. It can point out when a function is getting too long or even if your code is a little confusing in spots. Fixing the issues it points out, will help keep your project more maintainable.
Both Codecov and Code Climate can be integrated with Travis CI to run automatically on a schedule and with each addition of new code.
7. Let's Practice
We just learned about some amazingly helpful tools for software engineering with python. Let's practice.