Python CI/CD essentials – automating a basic task

A big yet understated part of DevOps is the thoroughness of the documentation that the process forces you to produce. The documentation does not have to be large; it does not have to be so comprehensive that it confuses people and makes them think twice about ever reading or writing documentation. It must be clear, concise, and to the point. And most of all, it must exist. Seriously, that last part is rarer than you think.

So, how do we use Python to facilitate the documentation process? Well, for this we can use a little library called Sphinx. Sphinx is a library written in Python that can be used to generate explicit documentation on a number of code bases, even those not written in Python. Sphinx is one of the most prominent tools for documentation. Most Python frameworks have their documentation written in it. You can install Sphinx through a lot of avenues in all available operating systems, but the one that we are going to use is the classic pip:

pip install sphinx

Once you have done this, go to the root directory of your project and initialize Sphinx using the following command:

sphinx-quickstart

You’ll be given a few settings for the setup. You can leave these as the default for now to get the sample document. You can later change this in the conf.py file.

Figure 9.1 – Quickstart menu for Sphinx

This will create an initial directory structure that can be built in HTML or LaTeX, among many other documentation formats.

Figure 9.2 – Completion of Sphinx setup

Now, let’s write a bit of Python code to use with our Sphinx generator.

Figure 9.3 – Initial code to be documented

You’ll notice the details in the code comments. These details are what Sphinx references when it creates the documentation. This is why open source projects emphasize code commenting on projects so much. If you ever encounter these comments in libraries, you now know why. Now, run a command to build an HTML file for documentation using the following:

make html

This will give you a documentation HTML file that you can host that looks something like this:

Figure 9.4 – Documentation HTML page

This was, of course, done manually. But with the correct documentation practices, it can be automated with a workflow that runs the preceding commands.

Now, whether you are an experienced DevOps engineer or a novice, you know that one of the main things that a DevOps person has to do (as experienced in this section) is work with developers and ask them to do things that will make the automation process and other DevOps processes smoother. One of the ways to gain a developer’s trust in this process is to make their lives easier in some way to prove your worth, and to just be a good co-worker in general. You can do that by being polite, always making a new cup of coffee if it finishes on your pour, holding the door for them… and also, as described in the next section, making their lives a little easier.