Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork7.9k
Description
as a followup to#9786 and more generally#7217
Update: Striked through done
Proposal: Additional docstring recommendations
While looking at and writing more documentation, I've come across different conventions in several aspects of the docstrings.
While one should not be too pedantic, and the world does not end if there are some variations, a set of of recommendations helps.
- It helps the user: Recognizable conventions throughout the docs. Better readability.
- It helps me as an author, because I don't always have to think anew about how to write certain patterns in the docs.
Structure of this proposal
For every aspect, if written a text to be included indocumentation guide in quotes:
Text for documentation.
Everything else are descriptions of the current state or explanations. One may consider adding the rationales.
Parameter type descriptions
#### Number type
Proposal:
Usescalar instead ofint orfloat if the type can be any number.
Current usage: Already often done, but not always. Just a hint for new writers.
#### array-like inputs
For array-like inputs, there are several notations:
- array_like / array-like
- sequence, sequence of [type]
- array
- iterable of [type]
Additionally, there are many variants to note length or dimensionality:
- shape(N,) / shape(2,N) / shape 2xN
- length N / length n
- 2-tuple / length 2-tuple / tuple of length 2
- 2 dimensional / 2-dimensional / two-dimensional / 2d / 2D / 2-D
Note: according tothis journal article 3D is more commonly used than 3-D.
suggestion t.b.d.
String values
Use simple single quotes when giving string values.
e.g.
If fmt is 'none', only the errorbars will be plotted.Rationale: 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.
Current usage: Already often done, but not always. Just a hint for new writers.
### Citing other types
Do we use~matplotlib.markers.MarkerStyle or.MarkerStyle?
Proposal:
Use full references
`~matplotlib.markers.MarkerStyle`in parameter types. Use abbreviated links`.MarkerStyle`in the text.
e.g.
norm : `~matplotlib.colors.Normalize`, optional, default: None A `.Normalize` instance is used to scale luminance data to 0, 1.Rationale: The distinction is only relevant for the plaintext string. The full reference is required if I want to find the corresponding doc (e.g. ipythonmatplotlib.colors.Normalize?). Therefore we write it in the type definition. In a text passage, readability has a higher priority. Therefore, we use abbreviated references.
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`.
Use partial references if the shorted form would be too generic, i.e.
`.Bbox.ignore`instead of`~.Bbox.ignore`or`~matplotlib.transforms.Bbox.ignore`.
e.g.
This depends on the last value passed to `.Bbox.ignore`.Rationale: The abbreviated from in the HTML should be easy to read. The link target gives the exact reference.
### Citing rcParams
Current variants:
- defaults to
``(lines.linewidth,)`` - defaults to rc
``image.cmap``/ defaults to rc`image.origin` - default is taken from the rcParam
``hist.bins`` - Default is
``rcParams['lines.markersize'] ** 2`` - default to rc settings
We should create a label.. _rc-paramshere.
When citing rcParams use a reference to the label
rc-paramsand the literal role for the parameter name.
e.g.
defaults to :ref:`rcParam<rc-params>` ``lines.linewidth``.Rationale: 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.
Note: If we would switch from the Sphinx default_roleobj toany, we could even leave out the:ref:.
Note 2: The objectrcParams 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.
Spaces after colon
Just noted that sometimes there's one space, sometimes there are two spaces. Not sure if it's worth mentioning.