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!

score 3 · Answer 1 · edited May 23 '17 at 12:08

3

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

edited May 23 '17 at 12:08

Community

1
1

answered Aug 23 '16 at 02:08

oraant

309
3
9

score 2 · Accepted Answer · edited May 23 '17 at 12:08

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

Thank you very much! Is there any way to change what pycharm expects? Also, using the formatting you posted, is there any way to indicate the types of the parameters and return values? — Juliano Foleiss, May 19 '16 at 14:01
They give details regarding this [here](https://www.jetbrains.com/help/pycharm/2016.1/using-docstrings-to-specify-types.html) although I'm not sure how you would change what it expects.. I have my own conventions, generally you'll still be able to see whatever you type as regular text, so try messing around a bit. — chrislessard, May 19 '16 at 15:00

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

2 Answers2