On Wed, Jun 15, 2016 at 7:29 PM, Cameron Hummels <chummels@gmail.com> wrote:
Looks cleaner, but you're right there are some rough edges, like how docstring examples are currently handled.  Example:


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@gmail.com> wrote:


On Wed, Jun 15, 2016 at 6:29 PM, Kacper Kowalik <xarthisius.kk@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@lists.spacepope.org
http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org


_______________________________________________
yt-dev mailing list
yt-dev@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

_______________________________________________
yt-dev mailing list
yt-dev@lists.spacepope.org
http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org