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 2)Join us and get access to thousands of tutorials and a community of expert Pythonistas.
Already a member? Sign-In
The full lesson is for members only. Join us and get access to thousands of tutorials and a community of expert Pythonistas.
Already a member? Sign-In
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!
Course Contents
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4