#416 Line length and titles when compiling notebooks with sphinx

[Matteo Bachetti]

Hello,
We are having a failure when compiling the documentation of our project

https://github.com/StingraySoftware/stingray/pull/550

The docs consist of rst files including a bunch of Jupyter notebooks. Sphinx now complains that one of them has line 930 that is too long. I don't understand what line it is referring to, because: 1) the ipynb raw code has a very short line 930 and 2) the compiled rst (with pandoc) does not have 930 lines... :)

When I try to debug in my computer, there is an additional error that comes out: sphinx complains about

/Users/meo/devel/spyder_projects/StingraySoftware/stingray/docs/notebooks/Pulsar/Pulsar search with epoch folding and Z squared.ipynb:1: WARNING: Each notebook should have at least one section title

But the exact same header formatting works fine in other Jupyter notebooks included in the same document. It only breaks down for that particular notebook.

Anyways, both failures happen only with docutils 0.17, not with 0.16 (see the failures in the PR I linked above).

Thanks a lot for your help, and sorry for the rather fuzzy description.

[Matteo Bachetti]

Someone just showed me that this was also reported to nbsphinx: https://github.com/spatialaudio/nbsphinx/issues/549

[Günter Milde]

Thank you for the report.

Could one of the lines in one of your notebooks be longer than the new line-lenght-limit default of 10 000 characters? (This limit was introduced in response to bug report #381 about possible DOS attacs, cf. https://docutils.sourceforge.io/docs/howto/security.html#cpu-and-memory-utilization.)

The line-length-limit can be configured programatically (see https://github.com/spatialaudio/nbsphinx/pull/552) or per-user in a Docutils configuration file:

An optional file docutils.conf can be added to the configuration directory to adjust Docutils configuration if not otherwise overridden or set by Sphinx.
-- https://www.sphinx-doc.org/en/master/usage/configuration.html

The misleading line number may be due to Sphinx or a Sphinx extension combining source documents before sending them to the Docutils parser.

[Günter Milde]

Please report back if increasing the line-length-limit solves the problem.
(The "title" warning may be a side-effect of a preceding too long line.)

The default limit of 10 000 characters/line are more than is expected of any
(re)structured text source. If Jupyter has special needs, it is free to programatically change the default.

[Matteo Bachetti]

Thanks Günter! Indeed, I use docutils through nbsphinx, and it is now clear that this is not a bug of docutils but the need for nbsphinx to adapt to the line-length-limit API change. I think that this bug report can be closed.
Thanks a lot for your help.