Generate documentation for python functions in a jupyter notebook using docstrings

Question:

There is a Jupyter Notebook with multiple python functions with docstrings. Is there a way to generate documentation for those functions without converting the notebook into a Python script?

Usually, documentation can be created for functions in a Python script or a project using a tool like pdoc3 and Sphinx, but couldn’t find a way to generate documentation directly from a notebook.

I have already tried using Sphinx on the notebook, but it seems to convert the entire notebook to a HTML file.

For instance, The following is one of the functions in the notebook.

def plot_calendar_map(df: pd.DataFrame, column: str, start_date: str, period_num: int, c_set: str = 'tab10') -> None:
    """Plot Calendar Maps for promotion run dates.
    
    Plots calendar maps indicating the days each promotion type has been active. In the current version, overlapping 
    promotions will be overwritten by the latest in the dataframe.
    
    Args:
        df: DataFrame containing promotion details
        column: Name of the dataframe column that contains promotion codes/identifiers
        start_date: Start date of the plot
        period_num: Length of the duration in days
        c_set: Color map names - matplotlib colormaps are supported
    
    Returns:
        None
        
    Examples:
        >>> plot_calendar_map(df = df, column = 'promo_code', start_date = '2019-01-01', period_num = 365)
    """
    ...

What I need is something like this (which was generated by pdoc3 after converting the notebook to a script.):

required outcome

Asked By: Hiran Hasanka

||

Answers:

Have you looked at nbdev?

From nbdev landing page:

"Create delightful software with Jupyter Notebooks
Write, test, document, and distribute software packages and technical articles — all in one place, your notebook."

From ‘How show_doc works’ section at nbdev documentation:

"When your documention website is built, all functions and classes you export to source code will be automatically documented with show_doc. This function outputs a summary of the symbol, showing its signature, docstring, and parameters. "


Related:

pdoc also auto-generates documentation. (Someone seemed to be trying to use it to make documentation from notebooks.)

Answered By: Wayne