pycharm quick documentation (CTRL+Q) not loading local documented file

Question

I'm using pycharm 2016.1.

I have a function documented as follows:

def extract_filename(filepath, ext=None):
    """
    This function returns the filename from a complete filepath including its extension.
    If ext is set to an extension it is removed from the filename.


    Parameters
    ----------
    filepath : string
    ext : string

    Returns
    -------
    string
    """

    if ext[0] != ".":
        ext = "." + ext

    filename = filepath.split("/")[-1]
    if ext is not None:
        filename = filename.split(ext)[0]

    return filename

I was expecting that once this documentation is in place, I'd be able to see it in the quick documentation window that pops up when I press CTRL + Q. However, this is not the case. The window only shows type inference:

def extract_filename(filepath, ext=None) Inferred type: (filepath: Union[str, unicode], ext: Union[str, unicode]) -> Union[str, unicode]

What am I missing here? I thought that by documenting my function its description and parameters would show up nicely formatted.

I found this post: Documenting Python parameters in docstring using PyCharm. However wish to use the NumPy format for writing documentation.

Thanks!

Answer 1

First at all, enter into settings panel: File -> Settings. Then search docstring, and change the Docstring format in this way:

Tools > Python Integrated Tools > Docstrings > Docstring format > NumPy

Visit https://stackoverflow.com/a/24385103/6324442 will help.

Some other doc: http://www.sphinx-doc.org/en/stable/ext/napoleon.html

Answer 2

It seems like everyone holds a different standard for Docstrings, and given the documentation found in PEP-257 I can see why you would've formatted things that way. PyCharm prefers this:

def function(arg1, arg2, ..., argn):
    """

    Description of the function and what it returns in an active tone.

    :param arg1: What the argument represents.
    ...
    :param argn: What the argument represents.

    :return: The meaning of the return value 
    """

Which, when applied to your code, would look like:

def extract_filename(filepath, ext=None):
   """ 

   Return the file name from a complete file path including its extension.
   If ext is set to an extension, remove it from the file name.

    :param  filepath: The full path to the file in question.
    :param ext: The extension for the file.

    :return: The filename from filepath including its extension. 
    """
    if ext[0] != ".":
        ext = "." + ext

    filename = filepath.split("/")[-1]
    if ext is not None:
        filename = filename.split(ext)[0]

    return filename