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.):

Wayne · Accepted Answer · 2023-03-09T18:07:22.083

1

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. "

edited Mar 09 '23 at 18:07

answered Mar 01 '23 at 15:50

Wayne

6,607
8
36
93

Thanks. Is there any way to use nbdev only to generate documentation into html or pdf files? It looks like a platform to manage entire repositories for code managed in notebooks. – Hiran Hasanka Mar 02 '23 at 13:23
Yes, I believe so. Granted things have gotten a little hard to find the minimal path as they have greatly expanded the abilities in the last couple of years; I think it is in there. The docs have a listing for [Documentation Only Sites](https://nbdev.fast.ai/tutorials/docs_only.html) and then under [Enter Quarto: A pandoc super-processor](https://nbdev.fast.ai/blog/posts/2022-07-28-nbdev2/index.html#enter-quarto-a-pandoc-super-processor) it mentions that the Quarto part of the tool chain gives the ability to make PDFs & it shows an image at the bottom of that section of a notebook & html. – Wayne Mar 02 '23 at 17:11
1

Thank you very much. Used Quarto for the task and it worked. – Hiran Hasanka Mar 02 '23 at 17:19

Generate documentation for python functions in a jupyter notebook using docstrings

1 Answers1

Linked