How to Create Documentation of Multiple .py Files using Pdoc

Problem Statement

Suppose your project's directory structure is like this:

- proj_root_dir
  - module_py_files_dir
    - general_functions.py
    - util_class.py
  - runnable_py_files_dir
    - main.py
  - documentation (optional, as pdoc creates it anyway)

And suppose you want to create documentation for the functions/modules found in module_py_files_dir.

Now, the solution is mentioned in the following sections.

Assuming You Created virtualenv Environment

If you've created a virtual environment for proj_root_dir, then first make sure that the pip currently selected is related to that environment by running:

pip -V

If not, make sure to select the Python interpreter related to the desired virtual environment (steps to do so on VSCode are here)

Side note: if you don't make sure you're using the right virtual environment, you may receive a ModuleNotFound error when trying to run the pdoc command later on.

Assuming You Created conda Environment

If you're dealing with Conda, then you will have one of two scenarios:

Either you use pip install or conda install. If you're using the former, then run the pip -V command as in the previous section.

In either case, you should then run conda info --envs and see which path is prefixed with *. If it the path of the conda environment you created, then you're good. If not, then you need to run conda activate PATH_TO_YOUR_ENV_FOLDER first.

Installing pdoc

Apparently, pdoc is not officially maintained by conda, so we'll just mention the pip installation command:

pip install pdoc3

That means that even if you have conda, it will use the pip package manager (inside of conda) to install pdoc, this is not considered best practice.

Running pdoc

Assuming the project directory structure mentioned in the first section of this post, the run command looks like this (adapted from this article):

pdoc --html "module_py_files_dir" --output-dir "documentation"

the --html command recursively searches for all .py files present in module_py_files_dir and converts them to .html pages found in documentation directory.

Caveats

What if for some reason, we have functions present in the main.py that we want pdoc to document as well? In that case, one of two scenarios will have happened:

Either you implemented the if __name__ == "__main__" guard, or you didn't.

Either way, pdoc should be run successfully, but be aware that pdoc runs the .py files, so if you didn't place that guard, then the code that should've been inside that guard will run, so ask yourself if this is something you want or not.

Outro

Hit me up if you have any questions ^^ 🙌:
LinkedIn
GitHub
Gmail: ashicsresources@gmail.com

But for now...