Creating the Sample Python Package
00:00 Create the Sample Python Package. To document a Python project, you first need a Python project. In this course, you’ll use a toy implementation of a calculator package that returns floating-point numbers.
00:15 If you already have a Python project for which you want to generate your documentation, then feel free to use that project instead. If that’s the case, you can skip this part and jump directly to the next section of the course.
00:28 Your example Python project will be small and consist only of one folder with two files in it, as seen on-screen. Create the package folder and the two files right inside your project folder.
00:47 Here’s how the two files are created on macOS,
00:59 and here’s how on Windows Terminal.
01:11
Then open calculations.py in your favorite code editor or IDE. Add the example code for some mathematical calculations that you’ll use as the basis for your documentation.
01:25 This code repackages some fundamental math operators into new functions that return the result as a floating-point number.
01:53
As seen on-screen, you’ll keep the second file, __init__.py, empty for now. For now, it’s here to help declare calculator as a package. Later on, you’ll add package-level docstrings in the file, which you’ll also pull into your auto-generated documentation.
02:09 In the next section of the course, you’ll add docstrings to your functions. This will set you up to allow you to generate documentation directly from these docstrings.
Christopher Trudeau RP Team on Dec. 7, 2025
Hi José,
Not my course, so I can’t speak directly for the creator, but I usually do it as a teaching aid. It is there so students know what file I’ve put something in and can match it to any sample code.
In some frameworks and scenarios the filename is important as well. For example in Django models.py has to be called that. Similarly, testing files typically need to be named starting with “test_”. Having the comment at the top just makes it clearer to the student where the code has to go.
In the field there isn’t really much purpose to it, although it is such a habit for me now that I probably do it there as well. :)
José Luis Cambil on Dec. 8, 2025
Hi Christopher,
It makes a lot of sense as a teaching aid. I hadn’t thought of that.
Thank you for the feedback! :)
Become a Member to join the conversation.
José Luis Cambil on Dec. 7, 2025
Hi! What’s the purpose of writing the module’s path on the first line? I’ve seen it in different tutorials, but I don’t know whether it’s just a convention or if it has any practical use. If it’s the former, wouldn’t it make refactoring harder if the project structure changes? Thanks!