Autogenerated documentation with Numpy docstring conventions

[janheindejong]

Problem

The theme doesn't seem to recognize the numpy docstring convention. Sections of the docstrings are formatted differently than in the example shown in the documention

Reproducible Project

These two docstrings, which describe the same thing, render very differently in the theme, where I prefer the second one.

def function_with_numpy_docstring(par1, par2): 
    """ This is a function with the numpy docstring 

    Parameters
    ------------
    par1: any 
        Some parameter 
    par2: any 
        Some other parameter

    Returns
    --------
    NoneType

    """
    return None 


def function_with_other_docstring(par1, par2): 
    """ This is a function with the docstring as in the readthedocs sphinx 
    theme example

    :param par1: Some parameter 
    :type par1: Any

    :param par2: Some parameter 
    :type par2: Any
    
    :rtype: NoneType

    """
    return None 

Expected Results

Ideally, I'd like to see numpy docstring formatted in the same way as in the Sphinx RTD theme example.

Environment Info

• Python Version: 3.7.2
• Sphinx Version: 2.0.1
• RTD Theme Version: 0.4.3

[leouieda]

I'm having a similar problem. Even when enabling numpydoc, the formatted version is messing up the parameter name a data type. For example, this is the exact same code with sphinx_rtd_theme 0.4.2 (https://www.fatiando.org/verde/v1.1.0/api/generated/verde.distance_mask.html#verde.distance_mask) and 0.4.3 (https://www.fatiando.org/verde/dev/api/generated/verde.distance_mask.html#verde.distance_mask). So this seems to be a new bug in the theme.

[xylar]

This was reported in sphinx here: sphinx-doc/sphinx#5959
and fixed here: sphinx-doc/sphinx#5976

Presumably a similar change to the sphinx RTD theme would take care of this?

[xylar]

Actually, the problem seems to have been fixed for me on RTD itself, I just see it when I try to build the docs locally. So probably in my case this is something still misconfigured or incompatible on my local build. The example links posted above also seem to look similar in new and old versions so I suspect this issue has been fixed.

[jessetan]

This may be a Sphinx 2 issue; the theme has a number of incompatibilities. @xylar are you using Sphinx 2 locally and a lower version on RTD perhaps?

[agjohnson]

Of the usable reports here, I don't see major issues. We could use some more information to track this down if you are still experiencing the issue. Agreed that this is probably in part a Sphinx 2 issue.

[agjohnson]

I'm going to close this due to lack of feedback. I think this will be addressed with some of the fixes for Sphinx 2.

[dizcza]

I'm still experiencing this issue with

sphinx==2.4.3
sphinx-rtd-theme==0.4.3/2/master

    Parameters
    ----------
    x_dim : int, optional
        state dimensionality
        Default: 3
    bin_size : float, optional
        spike bin width in msec
        Default: 20.0

Adding

.classifier:before {
    font-style: normal;
    margin: 0.2em;
    content: ":";
}

in css/custom.css and html_css_files = ['css/custom.css'] as mentioned in qutip/qutip-doc#94 has no effect.

Project link: https://elephant-docs-development.readthedocs.io/en/enh-module_doc/reference/gpfa.html#elephant.gpfa.gpfa.GPFA

however, by the time you inspect our url, it might be changed to a different sphinx theme. Although I like rtd-theme, if it doesn't work and I see no updates on this since Oct, we'll stick to a different one.

[xylar]

As another example of the problem, I don't use RTD anymore because my environment requires too much memory but I build my documentation for GitHub Pages using Travis CI and sphinx_rtd_theme, and I'm seeing the issue.

Here is an example of the problem from my docs:
https://mpas-dev.github.io/MPAS-Analysis/stable/generated/mpas_analysis.shared.analysis_task.AnalysisTask.html#mpas_analysis.shared.analysis_task.AnalysisTask

My CI is here if anyone wants to poke around but building the docs is basically just a question of setting up a conda environment including sphinx_rtd_theme and running make html in the docs directory.

https://github.com/MPAS-Dev/MPAS-Analysis/tree/develop/ci

[leouieda]

I managed to track down this problem to numpydoc (though not really what in numpydoc causes it). In fatiando/verde#209 we replaced numpydoc with sphinx.ext.napoleon to get roughly the same results but without the bad parameter list (example docstring).

[agjohnson]

If the issue is the classifier part of the definition list, this is a duplicate of #746 and will be resolved with #838.