search

pandas-dev / pandas

Flexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more
https://pandas.pydata.org
BSD 3-Clause "New" or "Revised" License
43.7k stars 17.92k forks source link

DOC: to quote or not to quote #19750

Open jorisvandenbossche opened 6 years ago

jorisvandenbossche commented 6 years ago

That's the question :-)

Whether we double-backtick-quote (to make it look like code) certain terms, such as Series and DataFrame, in our documentation is at the moment rather inconsistent. And @jreback recently started to regularly ask during reviews to quote them. And it is certainly good to be consistent on this, but I am personally not sure I find the quoted version better (and I have the feeling it will give more work while reviewing). It's not the most important issue, but since we are putting work in it to make it consistent (eg PRs of @tommyod eg https://github.com/pandas-dev/pandas/pull/19747 and older ones, and the reviewing comments we give), I thought this could be discussed.

So currently we use both DataFrame and DataFrame a lot throughout the docs, the unquoted version a little bit more (based on a quick grep of the text in the user guide (so without code-blocks), I see 418 times un-quoted DataFrame(s) and 241 quoted, and 273 unquoted Series and 187 quoted). But just to say we are not really consistent at the moment. And in our docstrings, I think we generally use the unquoted version.

So as you can guess, my preference would be to keep them mostly unquoted. My reason: in my opinion, this keeps the text "lighter", to not have code-formatted words constantly, code-formatting them gives more distraction in reading it. Plus, it will highlight those methods that we do quote more, to a reader skimming the text will more quickly see what methods it is about.

In general small code snippets and methods should be quoted (although that actually every method that appears in the text should be a reference to their docstring), but DataFrame and Series are such common words and often used in general without always explicitly referring to the class (code-wise), that IMO it is not needed to quote them.

tommyod commented 6 years ago

Personally I have no strong preference either way. I've been quoting DataFrame, Series, True/False, and keyword_arg=value as a general rule when reading the docs and submitting PRs. It seems constructive to agree to a common rule.

Perhaps quoting True/False and keyword_arg=value, and leaving Series, DataFrame and NaN unquoted. Methods and functions could always be linked to, even if appearing twice in a sentence.

jorisvandenbossche commented 6 years ago

Perhaps quoting True/False and keyword_arg=value, and leaving Series, DataFrame and NaN unquoted. Methods and functions could always be linked to, even if appearing twice in a sentence.

Yes, I certainly agree we should quote code-snippets as said above (and with that I also meant things like keyword_arg=value, as subset of a code line).

jreback commented 6 years ago

certainly agree to quoting True/False, NaN, and kwarg expressions. I don't really like the italics (and prefer quoting) generally. I personally DO like quoting Series/DataFrame in the docs. I am mixed about quoting in doc-strings, because they are rendered as text quite a lot and it is slightly distracting, but obviously nicer when html rendered.

Would it be possible to not quote DataFrame/Series, but then actually insert them on the rendering?

This solves the lightweight problem & I think can be done unambiguously (e.g. DataFrame/Series with a space in front and not followed by . or ()

I would prefer to keep the quoting in the docs personally.

TomAugspurger commented 6 years ago

I prefer reference to :class:`DataFrame` when appropriate, but not more than once in a section or so. For the rest, I think unquoted is fine.

rhshadrach commented 12 hours ago

It seems to me the current opinion is to have no hard rule, but to no over-link or backtick a section. I think this is fine, but I believe that necessarily means we have to give up shooting for any kind of consistency (since there is no rule to be consistent on). Marking as a closing candidate.