DOC: replace 'this platform' with the actual platform in the scalar type documentation #18085
Conversation
in the scalar documentation it's unclear that 'this platform' refers to the platform that the doc build job ran on, so replace it with the name of the platform using python's platform module
|
Remember these docstrings have to also make sense for users of Some other options:
|
| def add_newdoc_for_scalar_type(obj, fixed_aliases, doc): | ||
| # note: `:field: value` is rST syntax which renders as field lists. | ||
| o = getattr(_numerictypes, obj) | ||
|
|
||
| character_code = dtype(o).char | ||
| canonical_name_doc = "" if obj == o.__name__ else ":Canonical name: `numpy.{}`\n ".format(obj) | ||
| alias_doc = ''.join(":Alias: `numpy.{}`\n ".format(alias) for alias in fixed_aliases) | ||
| alias_doc += ''.join(":Alias on this platform: `numpy.{}`: {}.\n ".format(alias, doc) | ||
| alias_doc += ''.join(":Alias on this platform ({} {}): `numpy.{}`: {}.\n ".format(platform.system(), platform.machine(), alias, doc) |
There was a problem hiding this comment.
Is system + machine better or worse than platform()?
(I have no idea)
There was a problem hiding this comment.
From what I can tell platform.system is pretty much the same as sys.platform. I threw in the platform.machine because I would expect what numeric types alias to each other would vary on the same OS between say, the 64 bit and 32 bit version. For example on my machine system + machine is Linux x86_64, and 'platformisLinux`.
There was a problem hiding this comment.
sorry, by platform I meant platform.platform()
There was a problem hiding this comment.
platform.platform has a ton of information (Linux-4.19.128-microsoft-standard-x86_64-with-glibc2.29 on my WSL2 setup), to the point where I think it would probably clutter up the documentation more than it would help if it were included more than once. Maybe have the full platform be somewhere on that page and then link back to it whenever 'this platform' is mentioned?
There was a problem hiding this comment.
agreed, this looks good as is.
| def add_newdoc_for_scalar_type(obj, fixed_aliases, doc): | ||
| # note: `:field: value` is rST syntax which renders as field lists. | ||
| o = getattr(_numerictypes, obj) | ||
|
|
||
| character_code = dtype(o).char | ||
| canonical_name_doc = "" if obj == o.__name__ else ":Canonical name: `numpy.{}`\n ".format(obj) | ||
| alias_doc = ''.join(":Alias: `numpy.{}`\n ".format(alias) for alias in fixed_aliases) | ||
| alias_doc += ''.join(":Alias on this platform: `numpy.{}`: {}.\n ".format(alias, doc) | ||
| alias_doc += ''.join(":Alias on this platform ({} {}): `numpy.{}`: {}.\n ".format(platform.system(), platform.machine(), alias, doc) |
There was a problem hiding this comment.
agreed, this looks good as is.
This pull changes the wording of the scalar type documentation so that it uses information from python's
platformmodule (specifically{platform.system()} ({platform.machine()}) instead of the phrase 'this platform', which does not make it obvious that 'this platform' refers to the platform the documentation was built on, as well as which platform that is.