[yt-dev] RFC: replacing numpydoc with napoleon

[Nathan Goldbaum]

On Wed, Jun 15, 2016 at 7:29 PM, Cameron Hummels <chummels at gmail.com> wrote:

> Looks cleaner, but you're right there are some rough edges, like how
> docstring examples are currently handled.  Example:
>
>
> https://tests.yt-project.org/job/yt_docs/929/artifact/sandbox/doc/build/html/reference/api/generated/yt.visualization.volume_rendering.volume_rendering.volume_render.html#yt.visualization.volume_rendering.volume_rendering.volume_render
>

FWIW, that doesn't render correctly now either:

http://yt-project.org/docs/dev/reference/api/generated/yt.visualization.volume_rendering.volume_rendering.volume_render.html#yt.visualization.volume_rendering.volume_rendering.volume_render

fix:

https://bitbucket.org/yt_analysis/yt/pull-requests/2239


>
>
> Overall, I like the switch if we can come up with an efficient way of not
> doing a ton of docstrings corrections into a different format to fix these
> rough edges.
>
> On Wed, Jun 15, 2016 at 4:48 PM, Nathan Goldbaum <nathan12343 at gmail.com>
> wrote:
>
>>
>>
>> On Wed, Jun 15, 2016 at 6:29 PM, Kacper Kowalik <xarthisius.kk at gmail.com>
>> wrote:
>>
>>> Hi all!
>>> As you may know, most of the yt's docstrings are written using so called
>>> "numpy-style" [1]. It's not a default Sphinx's format and it requires an
>>> extension to parse it. Up till now we've been using numpydoc [2] to handle
>>> it. However, numpydoc is a bit buggy and not actively developed. My main
>>> issue with numpydoc is that it throws a bazillion of bogus warnings
>>> bloating jenkins logs to 100Mb for every docs' build.
>>>
>>> There's an alternative extension: napoleon [3] that I'd like to try. The
>>> resulting documentation looks a bit different and it may also require a
>>> little bit of work to iron out the rough edges.
>>> I issued a PR 2238 [4] to show docs with the new look.
>>>
>>>
>> I like the new look. It'll certainly be nice to clear these annoying
>> repetitive warning messages that get dumped to our doc build output.
>>
>> If anyone has issues, we should be able to tweak the appearance by
>> adjusting the CSS in our docs theme.
>>
>>
>>> I'd appreciate your comments.
>>> Cheers,
>>> Kacper
>>>
>>> [1]
>>> https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#class-docstring
>>> [2] https://pypi.python.org/pypi/numpydoc
>>> [3] http://www.sphinx-doc.org/en/stable/ext/napoleon.html
>>> [4] https://bitbucket.org/yt_analysis/yt/pull-requests/2238
>>> _______________________________________________
>>> yt-dev mailing list
>>> yt-dev at lists.spacepope.org
>>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>>
>>
>>
>> _______________________________________________
>> yt-dev mailing list
>> yt-dev at lists.spacepope.org
>> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>>
>>
>
>
> --
> Cameron Hummels
> NSF Postdoctoral Fellow
> Department of Astronomy
> California Institute of Technology
> http://chummels.org
>
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20160615/67711412/attachment.html>