How to generate a documentation for Python project using pdoc
English is not my mother tongue and I’m trying to improve my knowledge, any feedback is appreciated.
Today I spent some hours searching an easy way to generate a documentation for a university project I’m working on.
The project is written in Python.
I tried pydoc but I didn’t like the design of the html page that it generates, at the end I found pdoc.
Pdoc is a software that can be used to generate a documentation for Python projects, it creates a beautiful html page to show all the informations about classes and it is also easy to use.
Let’s see how to generate a documentation for a python project:
- First of all we need to install pydoc using the following command:
pip3 install pdoc3
- Then we need to go to the project folder. I recommend you to organize the project using two folders, one for the source code and one for the documentation.
In my case I have the folder Code and internally I created the folder src with the source code of my project.
- We need to add the current path to the PYTHONPATH to avoid an error that can occurr when we try to run pdoc.
- Paste the following command in your terminal:
YOURPATH is the path of the folder that contains /src, in my case is “/Users/lucacorbucci/Assignment/Code/”
- Now we can create the documentation with the following command:
pdoc — html src — html-dir docs
src is the folder that contains the source code and docs is the destination folder of the html files.
If you open the index.html file you should see a page like the one in the picture.