You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by GitBox <gi...@apache.org> on 2022/01/11 15:03:26 UTC
[GitHub] [arrow] amol- edited a comment on pull request #11726: ARROW-14738: [Python][Doc] Make return types clickable
amol- edited a comment on pull request #11726:
URL: https://github.com/apache/arrow/pull/11726#issuecomment-1010050324
@jorisvandenbossche
Looking at `numpydoc` there are a few things that come to my mind:
1) We should avoid the form `list of int` because `of` is nowhere recognised for containers, containers are dealt with `list[int]` form. Se should probably migrate all cases to that form because it solves some misunderstandings from numpydoc
2) numpydoc is somewhat buggy, `or` is only detected as a literal in some cases, in some other cases is parsed as a reference and becomes ``obj:`or` ``.
3) Some words it's correct that they are identified as generic references (`function`, `Mapping`, `iterator`) as they are in practice interfaces/protocols, so they might not have a reference in the Python docs but we want to identify them as code anyway.
My suggestion would be to apply (1) and solve (2) using `numpydoc_xref_ignore = {"or", "and", "of", ",", "default", "optional"}`. For `bool`, `True`, `False`, `object` I think it would be wrong to place them in ignore as they are currently correctly detected and linked to the Python documentation.
That solves the majority of cases, few instances of problems still remain like
where `depending on` still remains as code
or
where the whole parameter is misinterpreted for unknown reasons.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org