[jira] [Created] (ARROW-13159) [Doc][Python] The use of IPython directive or doctest code blocks in the python user guide

["Joris Van den Bossche (Jira)" <ji...@apache.org>]

Joris Van den Bossche created ARROW-13159:
---------------------------------------------

             Summary: [Doc][Python] The use of IPython directive or doctest code blocks in the python user guide
                 Key: ARROW-13159
                 URL: https://issues.apache.org/jira/browse/ARROW-13159
             Project: Apache Arrow
          Issue Type: Improvement
          Components: Documentation, Python
            Reporter: Joris Van den Bossche


From https://github.com/apache/arrow/pull/10266#discussion_r630837422

We are currently using the IPython directive in many places in the Python docs, so that something written as 

{code}
.. ipython:: python

  x = 1
  x + 2
{code}

is converted during the doc build to (by running the code):

{code}
.. code-block:: ipython

  In [1]: x = 1 

  In [2]: x + 1
  Out[2]: 2
{code}

Running all the code during the doc build can be costly, and the more docs we add, the slower building the docs becomes.

We could convert all those to {{code-block}}, but personally I think ideally we still check the code examples for correctness, where applicable. For this, we could also use the doctest format instead of the IPython directive, and verify the docs using pytest doctests support. 

This can be run separate as tests, and doesn't need to be part of doc building (at least when you only change wording / rst syntax, and want to verify the resulting html, you don't need to run the doctests).

But maintaining examples as doctests also certainly adds some extra cost (eg when outputs change slightly)

Another option could also be to add an option to the IPython directive to skip the execution of the code examples (I think this should be rather easy to add to the IPython directive, but then it's still a matter of passing this through from the build command invocation).

cc [~apitrou] [~amol-] 



--
This message was sent by Atlassian Jira
(v8.3.4#803005)