[yt-dev] RFC: replacing numpydoc with napoleon

[Kacper Kowalik]

On 06/15/2016 07:29 PM, Cameron Hummels 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

"Example" in this one is actually wrong (header should be marked with 
----) Original numpydoc version looks slightly better, but it's more of 
a coincidence than intended behaviour.

Cheers,
Kacper

> 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
>>
>>
>
>
>
>
> _______________________________________________
> yt-dev mailing list
> yt-dev at lists.spacepope.org
> http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
>