René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Additional docstring recommendations","articleBody":"as a followup to #9786 and more generally #7217 \r\n\r\n**Update: Striked through done**\r\n\r\n## Proposal: Additional docstring recommendations\r\n\r\nWhile looking at and writing more documentation, I've come across different conventions in several aspects of the docstrings.\r\n\r\nWhile one should not be too pedantic, and the world does not end if there are some variations, a set of of recommendations helps.\r\n\r\n- It helps the user: Recognizable conventions throughout the docs. Better readability.\r\n- It helps me as an author, because I don't always have to think anew about how to write certain patterns in the docs.\r\n\r\n### Structure of this proposal\r\n\r\nFor every aspect, if written a text to be included in [documentation guide](http://matplotlib.org/devdocs/devel/documenting_mpl.html#documenting-matplotlib) in quotes:\r\n\r\n\u003e Text for documentation.\r\n\r\nEverything else are descriptions of the current state or explanations. One may consider adding the rationales.\r\n\r\n### Parameter type descriptions\r\n\r\n\u003cs\u003e#### Number type\r\nProposal:\r\n\u003e Use *scalar* instead of *int* or *float* if the type can be any number.\r\n\r\nCurrent usage: Already often done, but not always. Just a hint for new writers.\u003c/s\u003e\r\n\r\n\u003cs\u003e#### array-like inputs\r\nFor array-like inputs, there are several notations:\r\n\r\n- array_like / array-like\r\n- sequence, sequence of [type]\r\n- array\r\n- iterable of [type]\r\n\r\nAdditionally, there are many variants to note length or dimensionality:\r\n\r\n- shape(N,) / shape(2,N) / shape 2xN\r\n- length N / length n\r\n- 2-tuple / length 2-tuple / tuple of length 2\r\n- 2 dimensional / 2-dimensional / two-dimensional / 2d / 2D / 2-D\r\n  Note: according to [this journal article](http://europeanscienceediting.eu/articles/3d-or-3-d-a-study-of-terminology-usage-and-style/) 3D is more commonly used than 3-D.\r\n\r\n\u003e suggestion t.b.d.\u003c/s\u003e\r\n\r\n### String values\r\n\r\n\u003e Use simple single quotes when giving string values.\r\n\r\ne.g. \r\n\r\n    If fmt is 'none', only the errorbars will be plotted.\r\n\r\nRationale: For the rendered docs, a litterally-quoted string ` ``'none'`` ` would look a bit nicer (similar to ``'none'``), but that's too difficult to type and too difficult to read in plaintext docs.\r\n\r\nCurrent usage: Already often done, but not always. Just a hint for new writers.\r\n\r\n\u003cs\u003e### Citing other types\r\n\r\nDo we use `~matplotlib.markers.MarkerStyle` or `.MarkerStyle`?\r\n\r\nProposal:\r\n\u003e Use full references `` `~matplotlib.markers.MarkerStyle` `` in parameter types. Use abbreviated links `` `.MarkerStyle` `` in the text.\r\n\r\ne.g.\r\n\r\n        norm : `~matplotlib.colors.Normalize`, optional, default: None\r\n            A `.Normalize` instance is used to scale luminance data to 0, 1.\r\n\r\nRationale: The distinction is only relevant for the plaintext string. The full reference is required if I want to find the corresponding doc (e.g. ipython `matplotlib.colors.Normalize?`). Therefore we write it in the type definition. In a text passage, readability has a higher priority. Therefore, we use abbreviated references.\r\n\r\n\u003e The displayed links of full references are abbreviated to the last component by preceding a tilde `` `~matplotlib.markers.MarkerStyle` ``. The abbreviation is not neccesary if the reference does only consist of one component anyway. For readability, do not use a tilde in these cases `` `.MarkerStyle` `` not `` `~.MarkerStyle` ``.\r\n\r\n\u003e Use partial references if the shorted form would be too generic, i.e. `` `.Bbox.ignore` `` instead of `` `~.Bbox.ignore` `` or `` `~matplotlib.transforms.Bbox.ignore` ``.\r\n\r\ne.g.\r\n \r\n    This depends on the last value passed to `.Bbox.ignore`.\r\n\r\nRationale: The abbreviated from in the HTML should be easy to read. The link target gives the exact reference.\u003c/s\u003e\r\n\r\n\u003cs\u003e### Citing rcParams\r\n\r\nCurrent variants:\r\n\r\n- defaults to ` ``(lines.linewidth,)`` `\r\n- defaults to rc ` ``image.cmap`` ` / defaults to rc `` `image.origin` ``\r\n- default is taken from the rcParam ` ``hist.bins`` `\r\n- Default is ` ``rcParams['lines.markersize'] ** 2`` `\r\n- default to rc settings\r\n\r\nWe should create a label `.. _rc-params` [here](https://matplotlib.org/devdocs/tutorials/introductory/customizing.html?highlight=rcparams#matplotlib-rcparams).\r\n\r\n\u003e When citing rcParams use a reference to the label `rc-params` and the literal role for the parameter name.\r\n\r\ne.g.\r\n\r\n    defaults to :ref:`rcParam\u003crc-params\u003e` ``lines.linewidth``.\r\n\r\nRationale: A link to the rcParams is helpfull, but it should be as short as possible in the plain text. One could also :ref:`rc-params`, but the link text would then depend on the section titile, which may not be good.\u003c/s\u003e\r\n\r\n*Note:* If we would switch from the Sphinx default_role `obj` to `any`, we could even leave out the `:ref:`.\r\n\r\n*Note 2:* The object `rcParams` is currently sometimes referenced, but that does not contain a list and description of the values. Also, there are several ways to influence the rcParams. So the above reference is more appropriate than the object. We should add a link from the object.\r\n\r\n### Spaces after colon\r\n\r\nJust noted that sometimes there's one space, sometimes there are two spaces. Not sure if it's worth mentioning.","author":{"url":"https://github.com/timhoffm","@type":"Person","name":"timhoffm"},"datePublished":"2018-01-11T02:07:29.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":11},"url":"https://github.com/10225/matplotlib/issues/10225"}