A Python docstring is a string used to document a Python module, class, function or method, so programmers can understand what it does without having to read the details of the implementation. Show Also, it is a common practice to generate online (html) documentation automatically from docstrings. Sphinx serves this purpose. The next example gives an idea of what a docstring looks like: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num2 Some standards regarding docstrings exist, which make them easier to read, and allow them be easily exported to other formats such as html or pdf. The first conventions every Python docstring should follow are defined in PEP-257. As PEP-257 is quite broad, other more specific standards also exist. In the case of pandas, the NumPy docstring convention is followed. These conventions are explained in this document:
numpydoc is a Sphinx extension to support the NumPy docstring convention. The standard uses reStructuredText (reST). reStructuredText is a markup language that allows encoding styles in plain text files. Documentation about reStructuredText can be found in:
pandas has some helpers for sharing docstrings between related classes, see . The rest of this document will summarize all the above guidelines, and will provide additional conventions specific to the pandas project. Writing a docstringGeneral rulesDocstrings must be defined with three double-quotes. No blank lines should be left before or after the docstring. The text starts in the next line after the opening quotes. The closing quotes have their own line (meaning that they are not at the end of the last sentence). On rare occasions reST styles like bold text or italics will be used in docstrings, but is it common to have inline code, which is presented between backticks. The following are considered inline code:
Note To display only the last component of the linked class, method or function, prefix it with def astype(dtype): """ Cast Series type. This section will provide further details. """ pass6. For example, def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7 will link to def astype(dtype): """ Cast Series type. This section will provide further details. """ pass8 but only display the last part, def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 as the link text. See for details. Good: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr) Bad: def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar Section 1: short summaryThe short summary is a single sentence that expresses what the function does in a concise way. The short summary must start with a capital letter, end with a dot, and fit in a single line. It needs to express what the object does without providing details. For functions and methods, the short summary must start with an infinitive verb. Good: def astype(dtype): """ Cast Series type. This section will provide further details. """ pass Bad: def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass def astype(dtype): """ Cast Series type Missing dot at the end. """ pass def astype(dtype): """ Cast Series type from its current type to the new type defined in the parameter dtype. Summary is too verbose and doesn't fit in a single line. """ pass Section 2: extended summaryThe extended summary provides details on what the function does. It should not go into the details of the parameters, or discuss implementation notes, which go in other sections. A blank line is left between the short summary and the extended summary. Every paragraph in the extended summary ends with a dot. The extended summary should provide details on why the function is useful and their use cases, if it is not too generic. def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass Section 3: parametersThe details of the parameters will be added in this section. This section has the title “Parameters”, followed by a line with a hyphen under each letter of the word “Parameters”. A blank line is left before the section title, but not after, and not between the line with the word “Parameters” and the one with the hyphens. After the title, each parameter in the signature must be documented, including def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass0 and def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass1, but not def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass2. The parameters are defined by their name, followed by a space, a colon, another space, and the type (or types). Note that the space between the name and the colon is important. Types are not defined for def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass0 and def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass1, but must be defined for all other parameters. After the parameter definition, it is required to have a line with the parameter description, which is indented, and can have multiple lines. The description must start with a capital letter, and finish with a dot. For keyword arguments with a default value, the default will be listed after a comma at the end of the type. The exact form of the type in this case will be “int, default 0”. In some cases it may be useful to explain what the default argument means, which can be added after a comma “int, default -1, meaning all cpus”. In cases where the default value is def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass5, meaning that the value will not be used. Instead of def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass6, it is preferred to write def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass7. When def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass5 is a value being used, we will keep the form “str, default None”. For example, in def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass9, def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass5 is not a value being used, but means that compression is optional, and no compression is being used if not provided. In this case we will use def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass7. Only in cases like def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass2 and def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass5 is being used in the same way as def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass4 or def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass5 would be used, then we will specify “str, int or None, default None”. Good: class Series: def plot(self, kind, color='blue', **kwargs): """ Generate a plot. Render the data in the Series as a matplotlib plot of the specified kind. Parameters ---------- kind : str Kind of matplotlib plot. color : str, default 'blue' Color name or rgb code. **kwargs These parameters will be passed to the matplotlib plotting function. """ pass Bad: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)0 Parameter typesWhen specifying the parameter types, Python built-in data types can be used directly (the Python type is preferred to the more verbose string, integer, boolean, etc):
For complex types, define the subtypes. For def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass6 and def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass7, as more than one type is present, we use the brackets to help read the type (curly brackets for def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass6 and normal brackets for def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass7):
In case where there are just a set of values allowed, list them in curly brackets and separated by commas (followed by a space). If the values are ordinal and they have an order, list them in this order. Otherwise, list the default value first, if there is one:
If the type is defined in a Python module, the module must be specified:
If the type is in a package, the module must be also specified:
If the type is a pandas type, also specify pandas except for Series and DataFrame:
If the exact type is not relevant, but must be compatible with a NumPy array, array-like can be specified. If Any type that can be iterated is accepted, iterable can be used:
If more than one type is accepted, separate them by commas, except the last two types, that need to be separated by the word ‘or’:
If def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass5 is one of the accepted values, it always needs to be the last in the list. For axis, the convention is to use something like:
Section 4: returns or yieldsIf the method returns a value, it will be documented in this section. Also if the method yields its output. The title of the section will be defined in the same way as the “Parameters”. With the names “Returns” or “Yields” followed by a line with as many hyphens as the letters in the preceding word. The documentation of the return is also similar to the parameters. But in this case, no name will be provided, unless the method returns or yields more than one value (a tuple of values). The types for “Returns” and “Yields” are the same as the ones for the “Parameters”. Also, the description must finish with a dot. For example, with a single value: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)1 With more than one value: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)2 If the method yields its value: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)3 Section 5: see alsoThis section is used to let users know about pandas functionality related to the one being documented. In rare cases, if no related methods or functions can be found at all, this section can be skipped. An obvious example would be the def astype(dtype): """ Cast Series type Missing dot at the end. """ pass1 and def astype(dtype): """ Cast Series type Missing dot at the end. """ pass2 methods. As def astype(dtype): """ Cast Series type Missing dot at the end. """ pass2 does the equivalent as def astype(dtype): """ Cast Series type Missing dot at the end. """ pass1 but at the end of the def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 or def astype(dtype): """ Cast Series type Missing dot at the end. """ pass6 instead of at the beginning, it is good to let the users know about it. To give an intuition on what can be considered related, here there are some examples:
When deciding what is related, you should mainly use your common sense and think about what can be useful for the users reading the documentation, especially the less experienced ones. When relating to other libraries (mainly def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass6), use the name of the module first (not an alias like def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass7). If the function is in a module which is not the main one, like def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass8, list the full module (e.g. def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass9). This section has a header, “See Also” (note the capital S and A), followed by the line with hyphens and preceded by a blank line. After the header, we will add a line for each related method or function, followed by a space, a colon, another space, and a short description that illustrates what this method or function does, why is it relevant in this context, and what the key differences are between the documented function and the one being referenced. The description must also end with a dot. Note that in “Returns” and “Yields”, the description is located on the line after the type. In this section, however, it is located on the same line, with a colon in between. If the description does not fit on the same line, it can continue onto other lines which must be further indented. For example: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)4 Section 6: notesThis is an optional section used for notes about the implementation of the algorithm, or to document technical aspects of the function behavior. Feel free to skip it, unless you are familiar with the implementation of the algorithm, or you discover some counter-intuitive behavior while writing the examples for the function. This section follows the same format as the extended summary section. Section 7: examplesThis is one of the most important sections of a docstring, despite being placed in the last position, as often people understand concepts better by example than through accurate explanations. Examples in docstrings, besides illustrating the usage of the function or method, must be valid Python code, that returns the given output in a deterministic way, and that can be copied and run by users. Examples are presented as a session in the Python terminal. class Series: def plot(self, kind, color='blue', **kwargs): """ Generate a plot. Render the data in the Series as a matplotlib plot of the specified kind. Parameters ---------- kind : str Kind of matplotlib plot. color : str, default 'blue' Color name or rgb code. **kwargs These parameters will be passed to the matplotlib plotting function. """ pass0 is used to present code. class Series: def plot(self, kind, color='blue', **kwargs): """ Generate a plot. Render the data in the Series as a matplotlib plot of the specified kind. Parameters ---------- kind : str Kind of matplotlib plot. color : str, default 'blue' Color name or rgb code. **kwargs These parameters will be passed to the matplotlib plotting function. """ pass1 is used for code continuing from the previous line. Output is presented immediately after the last line of code generating the output (no blank lines in between). Comments describing the examples can be added with blank lines before and after them. The way to present examples is as follows:
A simple example could be: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)5 The examples should be as concise as possible. In cases where the complexity of the function requires long examples, is recommended to use blocks with headers in bold. Use double star class Series: def plot(self, kind, color='blue', **kwargs): """ Generate a plot. Render the data in the Series as a matplotlib plot of the specified kind. Parameters ---------- kind : str Kind of matplotlib plot. color : str, default 'blue' Color name or rgb code. **kwargs These parameters will be passed to the matplotlib plotting function. """ pass4 to make a text bold, like in class Series: def plot(self, kind, color='blue', **kwargs): """ Generate a plot. Render the data in the Series as a matplotlib plot of the specified kind. Parameters ---------- kind : str Kind of matplotlib plot. color : str, default 'blue' Color name or rgb code. **kwargs These parameters will be passed to the matplotlib plotting function. """ pass5. Conventions for the examplesCode in examples is assumed to always start with these two lines which are not shown: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)6 Any other module used in the examples must be explicitly imported, one per line (as recommended in ) and avoiding aliases. Avoid excessive imports, but if needed, imports from the standard library go first, followed by third-party libraries (like matplotlib). When illustrating examples with a single def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 use the name class Series: def plot(self, kind, color='blue', **kwargs): """ Generate a plot. Render the data in the Series as a matplotlib plot of the specified kind. Parameters ---------- kind : str Kind of matplotlib plot. color : str, default 'blue' Color name or rgb code. **kwargs These parameters will be passed to the matplotlib plotting function. """ pass7, and if illustrating with a single def astype(dtype): """ Cast Series type Missing dot at the end. """ pass6 use the name class Series: def plot(self, kind, color='blue', **kwargs): """ Generate a plot. Render the data in the Series as a matplotlib plot of the specified kind. Parameters ---------- kind : str Kind of matplotlib plot. color : str, default 'blue' Color name or rgb code. **kwargs These parameters will be passed to the matplotlib plotting function. """ pass9. For indices, def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)00 is the preferred name. If a set of homogeneous def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9 or def astype(dtype): """ Cast Series type Missing dot at the end. """ pass6 is used, name them def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)03, def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)04, def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)05… or def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)06, def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)07, def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)08… If the data is not homogeneous, and more than one structure is needed, name them with something meaningful, for example def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)09 and def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)10. Data used in the example should be as compact as possible. The number of rows is recommended to be around 4, but make it a number that makes sense for the specific example. For example in the def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)11 method, it requires to be higher than 5, to show the example with the default values. If doing the def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)12, we could use something like def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)13, so it is easy to see that the value returned is the mean. For more complex examples (grouping for example), avoid using data without interpretation, like a matrix of random numbers with columns A, B, C, D… And instead use a meaningful example, which makes it easier to understand the concept. Unless required by the example, use names of animals, to keep examples consistent. And numerical properties of them. When calling the method, keywords arguments def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)14 are preferred to positional arguments def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)15. Good: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)7 Bad: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)8 Tips for getting your examples pass the doctestsGetting the examples pass the doctests in the validation script can sometimes be tricky. Here are some attention points:
Plots in examplesThere are some methods in pandas returning plots. To render the plots generated by the examples in the documentation, the def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)20 directive exists. To use it, place the next code after the “Examples” header as shown below. The plot will be generated automatically when building the documentation. def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar4 Sharing docstringspandas has a system for sharing docstrings, with slight variations, between classes. This helps us keep docstrings consistent, while keeping things clear for the user reading. It comes at the cost of some complexity when writing. Each shared docstring will have a base template with variables, like def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)21. The variables filled in later on using the def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)22 decorator. Finally, docstrings can also be appended to with the def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)22 decorator. In this example, we’ll create a parent docstring normally (this is like def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)24. Then we’ll have two children (like def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)25 and def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)26). We’ll substitute the class names in this docstring. def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar5 The resulting docstrings are def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar6 Notice:
Our files will often contain a module-level def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)27 with some common substitution values (things like def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)28, def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)29, etc). You can substitute and append in one shot with something like def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar7 where def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)30 may come from a module-level def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)31 dictionary mapping function names to docstrings. Wherever possible, we prefer using def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)22, since the docstring-writing processes is slightly closer to normal. |