jorisvandenbossche commented on pull request #11726: URL: https://github.com/apache/arrow/pull/11726#issuecomment-1009968625
Personally, I find https://github.com/apache/arrow/pull/11726#issuecomment-999340607 a somewhat annoying issue to ship as is (the strange formatting of the type list). I looked a bit into what numpydoc is doing here, and it seems that it is not very smart in how it tries to create links. Basically every word in the type section in the docstring gets transformed in a reference, and thus if nothing linkable is found by sphinx, it gets rendered as code. That's the reason you get "of" in "list of Array" rendered as code. Now, for a solution for this, I currently see two options: Option 1 is to use the numpydoc feature `numpydoc_xref_ignore` (specified in `conf.py`) to list a set of words that should be ignored and not transformed in a reference. Having checked the Table page (https://arrow.apache.org/docs/python/generated/pyarrow.Table.html, the screenshot above is from that page), this would already give something like: ``` numpydoc_xref_ignore = { "optional", "default", "None", "True", "False", "or", "of", "iterator", "function", "object", # TODO those could be removed if we rewrite the docstring a bit "values", "coercible", "to", "arrays", } ``` Option 2 could be to use some custom CSS to let the code in the type explanation look like normal text. That would be something like: ```css span.classifier code.xref span.pre { color: rgba(var(--pst-color-text-base),1); font-family: var(--pst-font-family-base); font-size: 1rem; } ``` This might actually be the "easier" solution, but it's a bit more a hack (while the other uses an actual numpydoc option), and is a bit less robust (eg if the html structure generated by sphinx changes). -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
