[yt-dev] RFC: replacing numpydoc with napoleon

[Cameron Hummels]

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

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.spacepope.org/pipermail/yt-dev-spacepope.org/attachments/20160615/d94971ff/attachment.html>