WARNING: Content block expected for the "raw" directive; none found.

[adamjstewart]

Congrats on the new release! We just noticed a change in behavior in our CI that we're having trouble debugging. When Sphinx tries to build the https://github.com/microsoft/torchgeo/blob/main/docs/tutorials/indices.ipynb file, it prints the warning:

~/torchgeo/docs/tutorials/indices.ipynb:15: WARNING: Content block expected for the "raw" directive; none found.

However, this file is all markdown, not rST, so we aren't directly using a "raw" directive. I'm not familiar with the inner workings of nbsphinx. Does it convert .ipynb files to .rst files so that Sphinx can convert .rst files to .html? If so, it would help to see the intermediate .rst file for this notebook to see where the "raw" directive is being added.

[calebrob6]

Following up here. It seems like the indices.ipynb file was executed on Google Collab. When we re-run this notebook in a local jupyter notebook environment then we do not observe the above warning.

[mgeier]

Does it convert .ipynb files to .rst files so that Sphinx can convert .rst files to .html?

Yes, but this is an implementation detail, see #36.

If so, it would help to see the intermediate .rst file for this notebook to see where the "raw" directive is being added.

There are (at least) two ways to do this:

1. use the save-rst branch (which I've just rebased for your convenience), which saves an .rst file next to each .html file.
2. use the (undocumented and unstable) nbsphinx API:

   >>> import nbsphinx
   >>> rststring, resources = nbsphinx.Exporter().from_file('indices.ipynb')
   >>> print(rststring)

Both should give you a reST document, but the second method doesn't includes things like nbsphinx_prolog, so there might be a few lines missing (so the line number in the warning message might be misleading).

Using the linked file above, I don't find anything suspicious on line 15, but maybe there are some project specific settings in place?

[mgeier]

PS: it looks like none of the two options contain nbsphinx_prolog and a few other things, so the line number might be off in both cases.

[adamjstewart]

Using the linked file above, I don't find anything suspicious on line 15, but maybe there are some project specific settings in place?

We recently updated that file to remove the offending metadata added by Colab, try with this commit: https://github.com/microsoft/torchgeo/blob/7d90045b9b2fe456dd42b3c1eb6819d7514825ad/docs/tutorials/indices.ipynb

[mgeier]

OK, I found the problem ... it can be quite brittle to programmatically generate reST files ...

The line number was confusing, the error was far from there, in the output of the cell starting with geometry = shapely.geometry.Polygon([...:

   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "                      \r"
     ]
    }
   ],

Since the output only contains whitespace, this led to a syntax error in the auto-generated reST file.

I've fixed this problem in #621.

[matthewfeickert]

Thanks for quickly finding the issue @mgeier. We're also seeing this error over on pyhf in our CI with the relevant change of

-nbsphinx                      0.8.7
+nbsphinx                      0.8.8

/home/runner/work/pyhf/pyhf/docs/examples/notebooks/learn/UsingCalculators.ipynb:15: WARNING: Content block expected for the "raw" directive; none found.
/home/runner/work/pyhf/pyhf/docs/examples/notebooks/multichannel-coupled-histo.ipynb:17: WARNING: Content block expected for the "raw" directive; none found.
/home/runner/work/pyhf/pyhf/docs/examples/notebooks/toys.ipynb:15: WARNING: Content block expected for the "raw" directive; none found.

where the notebooks in question are

• UsingCalculators.ipynb
• multichannel-coupled-histo.ipynb
• toys.ipynb

I see that you've already made a patch for this in PR #621 (:pray:) so I'll install from your fork in CI and see if that fixes things.

edit: Yeah, a diff of

@@ -31,6 +31,13 @@ jobs:
         python -m pip list
         sudo apt-get update
         sudo apt-get -qq install pandoc
+
+    - name: Patch dependencies
+      run: |
+        python -m pip uninstall -y nbsphinx
+        python -m pip install --upgrade "git+https://github.com/mgeier/nbsphinx.git@protect-from-empty-text#egg=nbsphinx"
+        python -m pip list
+
     - name: Check docstrings
       run: |
         # Group 1 is related to docstrings

fixes our CI. :+1: