[
https://issues.apache.org/jira/browse/ARROW-13159?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17385523#comment-17385523
]
Alessandro Molina commented on ARROW-13159:
-------------------------------------------
FYI, this seems to be the set of files where {{ipython}} directive is used
{code}
source/python/data.rst
source/python/dataset.rst
source/python/ipc.rst
source/python/memory.rst
source/python/pandas.rst
source/python/parquet.rst
{code}
> [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
> Priority: Major
>
> 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)
