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.
To use Pdoc you have to comment your code using Docstring, if your favourite IDE is VSCode I suggest you to install this extension.
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:
export PYTHONPATH=”/YOURPATH/”
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.
