Render numpydoc strings from a template

[jnothman]

In scikit-learn, we would like to start tracking the upstream numpydoc (scikit-learn/scikit-learn#7355). However, we currently render Attributes closely after Parameters, due to their significance, etc. Numpydoc renders Attributes after examples, notes, references, etc. which we find unideal.

This patch allows us to add templates/numpydoc_doscstring.rst containing:

{{index}}
{{summary}}
{{extended_summary}}
{{parameters}}
{{returns}}
{{yields}}
{{other_parameters}}
{{attributes}}
{{raises}}
{{warns}}
{{warnings}}
{{see_also}}
{{notes}}
{{references}}
{{examples}}
{{methods}}

to achieve the sought reordering. It is clearly also much more flexible than that, but I do not have (many) grand designs as yet.

[jnothman]

Ping @amueller

[amueller]

Wow that's much better than what I had in mind.

[jnothman]

Btw, I'm not entirely happy with how the template variable is being set / passed; and I'm confused as to whether this should affect NumpyDocString.__str__ too.

[amueller]

gotta review this soon... how do numpydoc folks like @rgommers @stefanv or @NelleV feel about adding this as an option?

[rgommers]

Related to gh-78, which was about having the section order fixed or not.

Having a fixed default ordering which is enforced by default but can be overridden/customized if you really want or need to would make sense to me.

[rgommers]

can you add jinja2 to install_requires?

[rgommers]

Very clean and simple implementation, I'd be fine with adding this.

[jnothman]

sphinx requires jinja2...?

…

On 29 November 2016 at 19:41, Ralf Gommers ***@***.***> wrote: Very clean and simple implementation, I'd be fine with adding this. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#77 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEz61jDgHqsKeGWvf4xOov0VLOZ8bhuks5rC-UogaJpZM4K3jJf> .

[stefanv]

I like the template implementation, but also: shouldn't attributes be rendered in the position suggested by default? This is the order in which is appears in the docstring and according to the standard.

[rgommers]

sphinx requires jinja2...?

I know, but explicit > implicit and all that. You normally put all your direct dependencies in install_requires.

[jnothman]

Of course.

[jnothman]

I run as far away from dependencies as I can :)

[jnothman]

I've added the jinja2 dependency, specifying the same version as current sphinx, though I assume an earlier version would work fine.

[rgommers]

I like the template implementation, but also: shouldn't attributes be rendered in the position suggested by default? This is the order in which is appears in the docstring and according to the standard.

Without checking: IIRC there's a long standing mismatch between docs and implementation for at least Methods and Attributes.

[rgommers]

@pv @stefanv any objection to merging this soon?

[stefanv]

Looks OK to me. @pv Do you have any thoughts on the section ordering?

[jnothman]

I'd really like to finally get scikit-learn using numpydoc directly. @amueller and I consider not having Attributes in its incumbent position a blocker. Can we please do something about it?

[rgommers]

No objections, so in it goes. Thanks @jnothman, all!