[
https://issues.apache.org/jira/browse/ARROW-13159?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17380274#comment-17380274
]
Weston Pace commented on ARROW-13159:
-------------------------------------
Have we measured the time these add? It seems it would depend on the script.
I tried with `code-block` vs `ipython` in `dataset.rst` and didn't see any
noticeable difference.
> [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)
