issue_comments

Table actions

8 rows where issue = 476222321 and user = 868027 sorted by updated_at descending

✎ View and edit SQL

This data as json, CSV (advanced)

Suggested facets: reactions, created_at (date), updated_at (date)

user 1

  • DocOtak · 8 ✖

issue 1

  • type annotations make docs confusing · 8 ✖

author_association 1

id html_url issue_url node_id user created_at updated_at ▲ author_association body reactions performed_via_github_app issue
555715128 https://github.com/pydata/xarray/issues/3178#issuecomment-555715128 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDU1NTcxNTEyOA== DocOtak 868027 2019-11-19T21:07:50Z 2019-11-19T21:07:50Z CONTRIBUTOR

Any recollection as to if these ever worked as expected? Looks like between landing this change and doing the 0.14 release, the sphinx version bumped from 2.1.2 to 2.2.0 which included some changes to autodoc... This PR might be of interest https://github.com/sphinx-doc/sphinx/pull/6592 but it is not immediately obvious to me how/if this could have broken things.

 
{
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321
517817952 https://github.com/pydata/xarray/issues/3178#issuecomment-517817952 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDUxNzgxNzk1Mg== DocOtak 868027 2019-08-02T19:27:45Z 2019-08-02T19:27:45Z CONTRIBUTOR

See #3180 for the napoleon enabling PR.

 
{
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321
517815307 https://github.com/pydata/xarray/issues/3178#issuecomment-517815307 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDUxNzgxNTMwNw== DocOtak 868027 2019-08-02T19:17:59Z 2019-08-02T19:17:59Z CONTRIBUTOR

So I made a PR for just removing the type annotations, turns out it is built in to autodoc. Enabling napoleon seems to be less "clean". While it doesn't actually conflict with numpydoc it does appear to "compete" with it. It only really seemed to affect the autowrapped ufunc documentation. I'm going to do a separate "enable napoleon" PR

 
{
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321
517786566 https://github.com/pydata/xarray/issues/3178#issuecomment-517786566 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDUxNzc4NjU2Ng== DocOtak 868027 2019-08-02T17:38:49Z 2019-08-02T17:38:49Z CONTRIBUTOR

Suspicions confirmed. I removed the type parts in the docstrings. The attached is the result which I think is way less readable: 

{
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321
517781349 https://github.com/pydata/xarray/issues/3178#issuecomment-517781349 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDUxNzc4MTM0OQ== DocOtak 868027 2019-08-02T17:22:10Z 2019-08-02T17:22:10Z CONTRIBUTOR

So I think why it isn't putting the types anywhere in the docs is because they already exist (at least for this Dataset __init__ that we are looking at).

The relevant part of the code in the extension appears to be this https://github.com/agronholm/sphinx-autodoc-typehints/blob/master/sphinx_autodoc_typehints.py#L333:L338

It's looking for :param name: and I think things with types are already :param type name: with napoleon enabled, so it doesn't find anything to replace. Without napoleon enabled, the :param name: fields are not present since it is "raw" numpy doc style.

 
{
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321
517772870 https://github.com/pydata/xarray/issues/3178#issuecomment-517772870 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDUxNzc3Mjg3MA== DocOtak 868027 2019-08-02T16:55:22Z 2019-08-02T16:55:22Z CONTRIBUTOR

So the plugin seems to "just works" in that it remove these data type annotation, it doesn't seem to put them anywhere. I can probably put the docs I built somewhere if you all want to look at them. Here is a screen shot of the "Dataset" class, first one is just the extension, second screenshot also has the napoleon extension enabled. Main difference is how the "parameters" appear. 

{
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321
517742116 https://github.com/pydata/xarray/issues/3178#issuecomment-517742116 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDUxNzc0MjExNg== DocOtak 868027 2019-08-02T15:23:46Z 2019-08-02T15:23:46Z CONTRIBUTOR

@dcherian sure, I'll try it right now with the xarray docs

 
{
    "total_count": 2,
    "+1": 2,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321
517734518 https://github.com/pydata/xarray/issues/3178#issuecomment-517734518 https://api.github.com/repos/pydata/xarray/issues/3178 MDEyOklzc3VlQ29tbWVudDUxNzczNDUxOA== DocOtak 868027 2019-08-02T15:03:07Z 2019-08-02T15:03:07Z CONTRIBUTOR

Perhaps the sphinx-autodoc-typehints extension?

The docs suggest it will remove the types from the method signatures and put them in the in :param: parts. I haven't used or tested myself.

 
{
    "total_count": 0,
    "+1": 0,
    "-1": 0,
    "laugh": 0,
    "hooray": 0,
    "confused": 0,
    "heart": 0,
    "rocket": 0,
    "eyes": 0
}
   type annotations make docs confusing 476222321

Advanced export

JSON shape: default, array, newline-delimited, object

CSV options: 

CREATE TABLE [issue_comments] (
   [html_url] TEXT,
   [issue_url] TEXT,
   [id] INTEGER PRIMARY KEY,
   [node_id] TEXT,
   [user] INTEGER REFERENCES [users]([id]),
   [created_at] TEXT,
   [updated_at] TEXT,
   [author_association] TEXT,
   [body] TEXT,
   [reactions] TEXT,
   [performed_via_github_app] TEXT,
   [issue] INTEGER REFERENCES [issues]([id])
);
CREATE INDEX [idx_issue_comments_issue]
    ON [issue_comments] ([issue]);
CREATE INDEX [idx_issue_comments_user]
    ON [issue_comments] ([user]);