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.

Unlock This Lesson

Documenting Your Python Projects (Part 2)

Documenting Code in Python Andrew Stephen 03:41

In this lesson, you’ll see what should be included in the documentation of your project. Here are the tools, references, and projects that are mentioned:

To continue your learning, you might want to check out the following:

Download

Sample Code (.zip)

1.6 KB

Download

Course Slides (PDF)

236.2 KB

Congratulations, you made it to the end of the course! What’s your #1 takeaway or favorite thing you learned? How are you going to put your newfound skills to use? Leave a comment in the discussion section and let us know.

00:00 Welcome to the seventh and final part of the Real Python tutorial for Documenting Your Python Code. Let’s go through the four main sections of the docs/ folder. At the 2017 PyCon, Daniele Procida gave a talk and subsequent blog post about documenting Python projects.

00:16 He mentions that all projects should have the following four major sections to help you focus your work.

00:23 Tutorials: Lessons that take the reader by the hand and go through a series of steps to complete a project or meaningful exercise. It is typically geared towards the user’s learning. How-to guides: Guides that take the reader through the steps required to solve a common problem.

00:41 Think of them as problem-oriented recipes. References: Explanations that clarify and illuminate a particular topic, geared towards the user understanding. And finally, explanations, which are technical descriptions of the machinery and how to operate it—key classes, functions, APIs, and so on. Think of this like an encyclopedic article.

01:03 This handy table gives a good visual on how these four sections relate to each other as well as their overall purpose. As you can see, tutorials and explanations are both most useful when studying, yet they are different in that tutorials are practical and explanations are theoretical. How-to guides and references follow the same sort of idea in that how-to guides are practical and references are theoretical, but they’re more useful when coding, as opposed to when you’re studying. Ideally, you are able to provide answers to any of the questions your users might have. By organizing your project in this way, you’ll be able to answer questions easily and in a format they can easily navigate. Tools and resources. Documenting your code, especially large projects, can be a daunting task. Thankfully, there are tools and reference materials available to get you started.

01:57 These include Sphinx, Epydoc, Read the Docs, Doxygen, MkDocs, and Pycco, just to list a few. These all vary in specific options they give you, but are all useful in their own rights. Along with these tools, additional tutorials, videos, and articles are available.

02:19 Examples of these can be found below, and are great starting points. Of course, sometimes mimicking others can be the best way to learn. Projects that can be found below are very good examples of having used documentation well.

02:33 You may find yourself asking “Where do I start?” The documentation of projects has a simple progression, going from no documentation, to some documentation, to complete documentation, to good documentation, and finally, you get to great documentation.

02:52 You can use this progression whenever you are at a loss as to where your documentation should go next. For example, if you have no documentation, then start there. If you have some, but are missing some key, recently-added aspects, start by remedying this first. Something to keep in mind is to not get discouraged or overwhelmed by the amount of work required to document your code. Once started, it becomes easier to continue, and if questions come up, there are many places—including right here at Real Python—where you can get some great advice. Congratulations! You’ve reached the end of this tutorial.

03:30 You now know all about documenting your Python code. I’m Andrew Stephen, and thanks for joining me on this documentation road. See you next time!

Thomas on Feb. 10, 2020

Thanks for this concise tutorial on documentation. Especially Epytext makes my life as a Java developer a lot easier writing Python documentation. I find this topic dead boring, but this tutorial made it a lot easier to get started:)

Andrew Stephen RP Team on Feb. 10, 2020

Hi Thomas, Glad this helped you out with getting started! Hopefully moving forward you become so proficient at your documentation that it no longer takes long enough to bore you ;)

Pierre on June 7, 2020

Thanks very much for the tutorial, Andrew. Been fumbling through the topic as an amateur coder using the Sphinx and ReadTheDocs docs. Nice to have your synthesis confirm I’m not totally out to lunch.

Ghani on Oct. 20, 2020

Very informative course; many thanks!

aniketbarphe on Sept. 22, 2021

Very informative course!

k-taylor on July 15, 2024

I think you have these mixed up?

References: Explanations that clarify and illuminate a particular topic, geared towards the user understanding. And finally, explanations, which are technical descriptions of the machinery and how to operate it—key classes, functions, APIs, and so on. Think of this like an encyclopedic article.

Become a Member to join the conversation.