Advanced Code Documentation Beyond Comments and Docstrings

Use Sphinx and Read the Docs for a user-friendly interface to understand codebase — even for non-technical users

Update: This article is part of a series. Check out Part 2, Part 3!

Documentation using Sphinx hosted on Read the Docs — Image by author

Documentation shows users how to use or understand a project, and there are different types of documentation depending on the project type. This article is for you if you are working on Python projects — whether it is writing a Python package or just a personal project, and you want your audience to understand the high-level details of what the code is doing, but not how it is done.

Understandability is important for any project, and a project is only as good as its documentation; it is useless if people other than the developer do not understand how it works. Documentation enables different developers to collaborate more effectively and is especially crucial when a project is being handed over from one person to the next.

Proper documentation not only saves a lot of time taken to understand the code but also saves the amount of frustration when something goes wrong.