Join us and get access to thousands of tutorials and a community of expert Pythonistas.
This lesson is for members only. Join us and get access to thousands of tutorials and a community of expert Pythonistas.
Documenting Your Python Projects (Part 1)
The documentation of your project will vary based on whether it is private, shared, or public. In this lesson, you’ll go through recommended documentation minimums for each type of project, and see why these particular parts are needed.
00:00 Welcome to Part 6 of the Real Python tutorial for Documenting Your Python Code. It’s now time to go over documenting your Python projects. Python projects can be any shape and size, and serve many and varied purposes.
00:14 Therefore, documentation will do the same. The way you document your specific project should suit your specific situation. Keep in mind who the users of your project are, who they’re going to be, and adapt as necessary to their needs.
00:29
Certain aspects of documentation are recommended depending on the type of project being created. The general layout of the project and its documentation should be as follows. With your project root, and then your project code, and then a folder called docs/, and then a handful of individual files.
00:49 Generally speaking, projects can be divided into three major types: private, shared, and public and open-source. Let’s look at private projects first.
01:01 As the name would suggest, private projects are projects that are intended to only ever be used by the writer, and generally won’t be released to be used by other users or developers.
01:13
This means that the documentation can be a little bit less comprehensive. There are some recommended paths, however. The README file, which is a brief summary of the project and its purpose. Include any special requirements for installation or operating the project. And examples.py, a Python script file that gives simple examples of how to use the project.
01:35
Keep in mind that even though it is intended to be used only by you, the creator, you are still a user. Consider what you may think to be confusing when coming back to the project down the road, and capture these aspects in comments, docstrings, or the README. Shared projects.
01:54 These are projects that are written in collaboration with only a few other people who are intended to use the project. The user of the project continues to be yourself, just like a private project, but now it also includes those limited few others. Documentation at this point should be a little more rigorous than our private project, mostly to help assist new members of the project to come up to speed or to alert contributors and users of new changes to the project.
02:22
Some of the recommended parts to add to the project are: A README, a brief summary of the project and its purpose. Include any special requirements for installation or operating the project, as well as any major changes from the previous version. examples.py, a Python script file that gives simple examples of how to use the project. And a How to Contribute,
02:46 which should include a how-to for new contributors coming onto the project.
02:51 Public and open-source projects are intended to be shared with the wider community and may involve large development teams. These projects should place as high a priority on project documentation as the actual development of the project itself.
03:06
Some of the recommended parts to add to the project are the following: A README, a brief summary of the project and its purpose. Include any special requirements for installation or operating the project, as well as any major changes from the previous version and add links to further documentation, bug reporting, and any other important information for the project. For further, more comprehensive assistance on a README, there is a very good tutorial available on the Real Python website.
03:35 How to Contribute, which should include a how-to for new contributors coming onto the project, including new features to develop, fixing known issues, adding further documentation, and adding new tests or reporting issues.
03:48 Code of Conduct file and a license file. The Code of Conduct file defines how other contributors should treat each other when developing or using this software.
03:59
It also states what will happen if the code is broken. If you’re using GitHub, a Code of Conduct template can be generated using recommended wording. For open-source projects especially, consider adding this. The license file is just a plaintext file that describes the license your project is using. Again, for open-source projects, you should consider adding this. Finally, there will also be a docs/ folder, which should contain further documentation.
04:27
Join me in the next and final part of this tutorial for a description of the docs/ folder and some documenting tools and resources.
Andrew Stephen RP Team on March 13, 2020
Hi @ron53white, what I actually say there is “consider adding this”, referring to the Code of Conduct file I had just been talking about. Sorry for the confusion!
ron53white on March 13, 2020
Thank you! (Probably need to put in my hearing aids.)
Become a Member to join the conversation.
ron53white on March 12, 2020
Sorry, more misunderstanding.
At about 4:07 we’re talking about using GitHub, and the recommended template should be used or added.
Then, “For Open Source projects especially, consider [unintelligible/garbled]”