0

I'm getting two warning messages when trying to build my docs with Sphinx v2.1.2 and sphinx-rtd-theme 0.4.3.

The first one is:

/docs/numsec.py:50: RemovedInSphinx30Warning: app.override_domain() is deprecated. Use app.add_domain() with override option instead.
  app.override_domain(CustomStandardDomain)

That section of my numsec.py looks like:

def setup(app):
    app.override_domain(CustomStandardDomain)
    app.connect('doctree-resolved', doctree_resolved)

I don't know what override option means. I've tried replacing that line with app.add_domain() and app.add_domain(CustomStandardDomain) but neither works.

The second warning message is:

/miniconda3/envs/py3/lib/python3.7/site-packages/sphinx_rtd_theme/search.html:20: RemovedInSphinx30Warning: To modify script_files in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
  {{ super() }}

and I have no idea of to fix this one. Should I just remove the {{ super() }} line?

Gabriel
  • 40,504
  • 73
  • 230
  • 404
  • 1
    First consult the Sphinx change history and repo to learn about upgrading from 2.1.2 to 3.0.x. http://www.sphinx-doc.org/en/master/changes.html and https://github.com/sphinx-doc/sphinx/search?q=override_domain&type=Commits Report back if that does not point you in the right direction. It looks like override_domain was deprecated in a beta for 1.8.x. – Steve Piercy Aug 07 '19 at 19:59
  • I tried the "simple" command shown in Sphinx's [own docs](https://www.sphinx-doc.org/en/master/usage/installation.html) (`apt-get install python3-sphinx`) and for some reason it decided to install v1.6.7. **Sigh**. – Gabriel Aug 07 '19 at 20:19
  • BTW the current version in Sphinx's site is still 2.1.2. Why would I need to upgrade it to v3.0? – Gabriel Aug 07 '19 at 20:22
  • `master` branch will be 3.0. Current release is 2.1.2. The warnings that you see are from the deprecation warnings added in 1.8.0b1. You can ignore the warnings, or prepare for future releases. You can also install the unreleased version of the rtd_sphinx_theme from GitHub to avoid that warning. – Steve Piercy Aug 07 '19 at 22:06

1 Answers1

4

For now, it is possible to just ignore the warnings. Everything will still work. But in Sphinx 3.0 (not yet released), the deprecated features will stop working.

The first warning goes away if you replace

app.override_domain(CustomStandardDomain)

with 

app.add_domain(CustomStandardDomain, override=True)

in numsec.py (which I presume is the same as https://github.com/jterrace/sphinxtr/blob/master/extensions/numsec.py).

The second warning is about a deprecated feature in search.html in sphinx-rtd-theme. This has already been fixed in the GitHub repository, but the fix is not in the latest release (0.4.3).

See https://github.com/readthedocs/sphinx_rtd_theme/commit/a49a812c8821123091166fae1897d702cdc2d627#diff-b3d4a9c32d5abd89b9214dcfbb2ece79.

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • Thank you for the detailed answer mzjn! – Gabriel Aug 07 '19 at 23:25
  • There are also ways to temporarily suppress warnings. See https://docs.python.org/3/library/warnings.html and https://stackoverflow.com/q/14463277/407651. – mzjn Jan 23 '20 at 10:59