Cannot build documentation with code marked using multiple directives

[mkelley]

[Edit by @bsipocz]: This seems to be a generic issue, not just with the specific directives below. Most recently we run into the issue with using doctest-remote-data:: along with plot::

---

When I mark a code block with multiple directives including doctest-requires Sphinx cannot build the documentation. For example:

.. doctest-requires:: sbpy
.. deprecated:: 1.0

    >>> 1 + 3
    2

Causes the following exception:

========================================================== 45 passed, 1 skipped in 4.95s ==========================================================
py310-test: commands[6] /home/msk/Projects/pytest-doctestplus/.tmp/py310-test> sphinx-build /home/msk/Projects/pytest-doctestplus/tests /home/msk/Projects/pytest-doctestplus/tests/_build/html -W
Running Sphinx v7.2.3
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed

Exception occurred:
  File "/home/msk/Projects/pytest-doctestplus/.tox/py310-test/lib/python3.10/site-packages/docutils/statemachine.py", line 1136, in __getitem__
    return self.data[i]
IndexError: list index out of range
The full traceback has been saved in /tmp/sphinx-err-yi3p0x_g.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
py310-test: exit 2 (0.51 seconds) /home/msk/Projects/pytest-doctestplus/.tmp/py310-test> sphinx-build /home/msk/Projects/pytest-doctestplus/tests /home/msk/Projects/pytest-doctestplus/tests/_build/html -W pid=936334
.pkg: _exit> python /home/msk/.venv/lib/python3.10/site-packages/pyproject_api/_backend.py True setuptools.build_meta
  py310-test: FAIL code 2 (30.41=setup[4.50]+cmd[0.40,4.63,4.48,5.00,5.53,5.36,0.51] seconds)
  evaluation failed :( (30.56 seconds)

The log file referenced above is:
sphinx-err-yi3p0x_g.log

The order does matter. The following block builds OK:

.. deprecated:: 1.0
.. doctest-requires:: sbpy

    >>> 1 + 3
    2

I've forked this repo and added a test file that shows this behavior: https://github.com/mkelley/pytest-doctestplus/tree/multiple-directives

Packages used in the failing test:

py310-test: commands[0] /home/msk/Projects/pytest-doctestplus/.tmp/py310-test> pip freeze
alabaster==0.7.13
Babel==2.12.1
certifi==2023.7.22
charset-normalizer==3.2.0
docutils==0.20.1
exceptiongroup==1.1.3
idna==3.4
imagesize==1.4.1
iniconfig==2.0.0
Jinja2==3.1.2
MarkupSafe==2.1.3
numpy==1.25.2
packaging==23.1
pluggy==1.2.0
Pygments==2.16.1
pytest==7.4.0
pytest-doctestplus @ file:///home/msk/Projects/pytest-doctestplus/.tox/.tmp/package/3/pytest-doctestplus-0.1.dev923%2Bg45fc0e9.tar.gz#sha256=891300698a4492ed6ebb4c9237744c3d4f8909142f115cb9fe1aad05c0559327
pytest-remotedata==0.4.0
requests==2.31.0
snowballstemmer==2.2.0
Sphinx==7.2.3
sphinxcontrib-applehelp==1.0.7
sphinxcontrib-devhelp==1.0.5
sphinxcontrib-htmlhelp==2.0.4
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.6
sphinxcontrib-serializinghtml==1.1.9
tomli==2.0.1
urllib3==2.0.4

[pllim]

A workaround that might work is to use this instead wherever you define your pytest options:

doctest_subpackage_requires =
    docs/sbpy/photometry.rst = scipy,astroquery,synphot
    docs/sbpy/activity/dust.rst = scipy

Looking at NASA-Planetary-Science/sbpy#383 , maybe you should just add scipy as required dependency?

[bsipocz]

I would have said that the order matters, but you noticed that, too. Maybe this is just a documentation issue?

[mkelley]

Thanks, that work around does get the docs to compile. scipy is not the main issue, but astroquery. I'd like to mark individual code-blocks with pytest-requires:: astroquery and pytest-remote-data::. Both packages have the same issue, so changing the order of these directives does not solve the problem. I guess I buried the lede. A separate work-around is to use # doctest: +REMOTE_DATA instead of pytest-remote-data:: (but that means adding a lot of comments to our documentation).

[bsipocz]

Oh, you mean the remote-data and requires are also order sensitive?

[mkelley]

Yes. I did not do a formal test with remote-data as I did with requires above, but the crash happens regardless of the order:

.. pytest-requires:: astroquery
.. pytest-remote-data::

vs.

.. pytest-remote-data::
.. pytest-requires:: astroquery

[seberg]

Isn't it because each directive is its own block, so nesting doesn't work unless you indent the nested one? Not sure how directives are added, but a single .. pytest:: directive with :options: might work?

[bsipocz]

I'm confused because some combination does work together while others do not. But I haven't really had a chance to dive into the details.

[bsipocz]

We now run into the issue of needing remote-data in a .. plot:: directive in astropy/astroquery#2855, for which there is no easy workaround.

(I mean, fixing #146 is probably the easiest workaround)