Skip to content

Render numpydoc strings from a template#77

Merged
rgommers merged 2 commits intonumpy:masterfrom
jnothman:templated-order
Dec 27, 2016
Merged

Render numpydoc strings from a template#77
rgommers merged 2 commits intonumpy:masterfrom
jnothman:templated-order

Conversation

@jnothman
Copy link
Copy Markdown
Member

@jnothman jnothman commented Nov 20, 2016 •
edited
Loading

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
Copy link
Copy Markdown
Member Author

jnothman commented Nov 20, 2016

Ping @amueller

@amueller
Copy link
Copy Markdown
Contributor

amueller commented Nov 20, 2016

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

@jnothman
Copy link
Copy Markdown
Member Author

jnothman commented Nov 21, 2016

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 amueller mentioned this pull request Nov 22, 2016
Merged
@amueller
Copy link
Copy Markdown
Contributor

amueller commented Nov 29, 2016

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

@rgommers
Copy link
Copy Markdown
Member

rgommers commented Nov 29, 2016

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
Copy link
Copy Markdown
Member

rgommers commented Nov 29, 2016

can you add jinja2 to install_requires?

@rgommers
Copy link
Copy Markdown
Member

rgommers commented Nov 29, 2016

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

@jnothman
Copy link
Copy Markdown
Member Author

jnothman commented Nov 29, 2016 via email

@stefanv
Copy link
Copy Markdown
Contributor

stefanv commented Nov 29, 2016

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
Copy link
Copy Markdown
Member

rgommers commented Nov 29, 2016

sphinx requires jinja2...?

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

@jnothman
Copy link
Copy Markdown
Member Author

jnothman commented Nov 29, 2016

Of course.

@jnothman
Copy link
Copy Markdown
Member Author

jnothman commented Nov 29, 2016

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

@jnothman
Copy link
Copy Markdown
Member Author

jnothman commented Nov 29, 2016

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

@rgommers
Copy link
Copy Markdown
Member

rgommers commented Dec 2, 2016

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
Copy link
Copy Markdown
Member

rgommers commented Dec 2, 2016

@pv @stefanv any objection to merging this soon?

@stefanv
Copy link
Copy Markdown
Contributor

stefanv commented Dec 3, 2016

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

@jnothman
Copy link
Copy Markdown
Member Author

jnothman commented Dec 26, 2016

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 rgommers merged commit de494ff into numpy:master Dec 27, 2016
@rgommers
Copy link
Copy Markdown
Member

rgommers commented Dec 27, 2016

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

@rgommers rgommers added this to the v0.7.0 milestone Dec 27, 2016
rgommers pushed a commit to rgommers/numpydoc that referenced this pull request Dec 27, 2016
BUG: fix installing numydoc, broken with missing templates after nump…
c9881fa 
…ygh-77.
rgommers added a commit that referenced this pull request Dec 27, 2016
@rgommers
Merge pull request #83 from rgommers/fix-install
18df9d1 
BUG: fix installing numpydoc, broken with missing templates after gh-77.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

type: Enhancement

Projects

None yet

Milestone

v0.7.0

Development

Successfully merging this pull request may close these issues.

4 participants

@jnothman @amueller @rgommers @stefanv