From 9bbf8903866d07b4ef347c548caeb5b4aee7494f Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Wed, 7 Mar 2018 11:22:39 +0100 Subject: [PATCH 1/2] DOC: add small guide on how to write examples that pass doctests --- doc/source/contributing.rst | 64 +++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index e159af9958fde..afa6225ab8306 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -430,6 +430,70 @@ the documentation are also built by Travis-CI. These docs are then hosted `here `__, see also the :ref:`Continuous Integration ` section. + +Writing examples that pass the doctest +-------------------------------------- + +The "Examples" section in the docstrings follows the `doctest `__ +format (lines beginning with ``>>>`` for code), and are also tested to ensure the +correctness of the examples shown in the API documentation. + +In general, the format looks like: + +:: + + Examples + -------- + + A small example: + + >>> s = pd.Series([1, 2, 3]) + >>> s + 0 1 + 1 2 + 2 3 + dtype: int64 + + Taking the mean: + + >>> s.mean() + 2.0 + +A single docstring can be tested using the ``validate_docstrings.py`` script +(from inside the pandas repository), for example:: + + python scripts/validate_docstrings.py pandas.DataFrame.mean + +Alternatively, you can use ``pytest --doctests-module pandas/core/series.py`` +to run all doctests of the ``Series`` class. + +Getting this tests to pass can however sometimes be tricky. Here are some +attention points: + +* Import all needed libraries (except for pandas and numpy, those are already + imported as `import pandas as pd` and `import numpy as np`) and define all + variables you use in the example. + +* Try to avoid using random data. + +* If you have a code lines that wraps multiple lines, you need to use '...' + on the continued lines: + + :: + + >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'], + ... columns=['A', 'B']) + +* If you want to show a case where an exception is raised, you can do:: + + >>> pd.to_datetime(["712-01-01"]) + Traceback (most recent call last): + OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00 + + It is essential to include the "Traceback (most recent call last):", but for + the actual error only the error name is sufficient. + + .. _contributing.code: Contributing to the code base From 1c94ab4ebc074f29d631493209bc2c9ebe08d173 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 8 Mar 2018 21:02:33 +0100 Subject: [PATCH 2/2] add ellipsis trick --- doc/source/contributing.rst | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index afa6225ab8306..ce356e91ec108 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -467,7 +467,7 @@ A single docstring can be tested using the ``validate_docstrings.py`` script Alternatively, you can use ``pytest --doctests-module pandas/core/series.py`` to run all doctests of the ``Series`` class. -Getting this tests to pass can however sometimes be tricky. Here are some +Getting this tests to pass can sometimes be tricky. Here are some attention points: * Import all needed libraries (except for pandas and numpy, those are already @@ -476,7 +476,7 @@ attention points: * Try to avoid using random data. -* If you have a code lines that wraps multiple lines, you need to use '...' +* If you have a code snippet that wraps multiple lines, you need to use '...' on the continued lines: :: @@ -493,6 +493,20 @@ attention points: It is essential to include the "Traceback (most recent call last):", but for the actual error only the error name is sufficient. +* If there is a small part of the result that can vary (e.g. a hash in an object + represenation), you can use ``...`` to represent this part. + + If you want to show that ``s.plot()`` returns a matplotlib AxesSubplot object, + this will fail the doctest:: + + >>> s.plot() + + + However, you can do (notice the comment that needs to be added):: + + >>> s.plot() # doctest: +ELLIPSIS + + .. _contributing.code: