How to Create Documentation of Multiple .py Files using Pdoc
Tags: documentation, python, tutorial, html
Published: 2024-02-19 12:35:27

## 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:

```powershell
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](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment))

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](https://github.com/pdoc3/pdoc/issues/21#issuecomment-759836017), so we'll just mention the pip installation command:

```powershell
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](https://github.com/pdoc3/pdoc/issues/21#issuecomment-546335424).

## Running `pdoc`

Assuming the project directory structure mentioned in the first section of this post, the run command looks like this (adapted from [this](https://lucacorbucci.medium.com/how-to-generate-a-documentation-for-python-code-using-pdoc-60f681d14d6e) article):

```powershell
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](https://github.com/pdoc3/pdoc/issues/138#issuecomment-567842767) 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](https://www.linkedin.com/in/ashrafharess/)
[GitHub](https://github.com/OdyAsh)
Gmail: ashicsresources@gmail.com

But for now...


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9c2fysv60a89d8r1yyt4.gif)