pdoc3 or Sphinx for directory with nested module

Question

My code directory looks like below. I need to generate documentation for all the modules like for sub1,sub2,submoduleA1,submoduleB1 and so on. Also as shown for submoduleB2.py: all the modules imports from other modules/submodules

<workspace>
└── toolbox (main folder)
    ├── __init__.py 
    │   
    ├── sub
    │   ├── __init__.py
    │   ├── sub1.py
    │   └── sub2.py     
    │   
    ├── subpackageA
    │   ├── __init__.py
    │   ├── submoduleA1.py
    │   └── submoduleA2.py
    │   
    └── subpackageB
        ├── __init__.py
        ├── submoduleB1.py
        └── submoduleB2.py code[from sub import sub1
                                from subpackageA import submoduleA2 and so on]

code structure for submoduleB2.py

from __future__ import absolute_import, division
import copy
import logging
import numpy as np
import pandas as pd
from dc.dc import DataCleaning
from sub.sub1 import ToolboxLogger
from subpackageA import pan

LOGGER = ToolboxLogger(
    "MATH_FUNCTIONS", enableconsolelog=True, enablefilelog=False, loglevel=logging.DEBUG
).logger

"""
Calculations also take into account units of the tags that are passed in

"""
def spread(tag_list):
    """
    Returns the spread of a set of actual tag values

    :param tag_list: List of tag objects
    :type tag_list: list
    :return: Pandas Series of spreads
    :rtype: Pandas Series
    :example:
        >>> tag_list = [tp.RH1_ogt_1,
                    tp.RH1_ogt_2,
                    tp.RH1_ogt_3,
                    tp.RH1_ogt_4,
                    tp.RH1_ogt_5,
                    tp.RH1_ogt_6]
        >>> spread = pan.spread(tag_list)
    """
    # use the same units for everything
    units_to_use = tag_list[0].units
    idxs = tag_list[0].actuals.index
    spread_df = pd.DataFrame(index=idxs)
    spread_series = spread_df.max(axis=1).copy()
    return Q_(spread_series, units_to_use)

I tried to run the pdoc command using anaconda prompt by navigating it to the toolbox folder and executed the below command

pdoc --html --external-links --all-submodules preprocess/toolbox/subpackageA

after executing this command a "subpackageA" folder was created under toolbox with index.html file but it was all blank

Then i tried to generate documentation by providing specific module name

pdoc --html --external-links --all-submodules preprocess/toolbox/submoduleB2.py

but received this below error: File "C:\Users\preprocess/toolbox/submoduleB2.py", line 16, in from sub import sub1 ImportError: No module named sub.sub1

Can you please tell me how to generate the documentation using pdoc for complete directory? Or is there any other package which will auto generate the documentation? I even tried Sphnix, but faced issues in adding the module/submodule paths in config file

Answer 1

It appears that pdoc3 is throwing that kind of error for a module if it cannot find an import into that module in the python path. One solution is to put

import os, sys
syspath = os.path.dirname(os.path.abspath(__file__))
sys.path.append(path)

into the __init__.py files in each of the subdirectories.