Cannot suppress circular toctree warnings with suppress_warnings

[asmeurer]

The suppress_warnings flag does not seem to support suppressing "circular toctree" warnings. I tried all the warnings at https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings and none of them supressed the warnings.

FWIW, I am using recommonmark and I found that I need to include index in its own toctree for it to show up in the sidebar.

I am using sphinx 2.4.4.

[tk0miya]

I don't understand why do you want to keep your toctree circular. IMO, no reason to suppress the warning message because it's unexpected status for Sphinx.

[asmeurer]

I am using this to include the full toc tree in the sidebar. I want this to include the main index page as well. If you have a suggestion of a better way to do this, let me know.

In general, though, I would want the table of contents to include the page with the table of contents itself. I don't understand why that is disallowed.

[tk0miya]

Thank you for explanation. I understand what you'd like to go. I think the proper way to do that is "self" keywords in toctree (refs: #4602). But it has not been implemented for a long time, unfortunately.

I can't recommend you to use circular toctree, because Sphinx expects that the structure of toctree is a "tree" model. In other words, circular toctree might cause bug or crash in some feature. But, I understand to use it as a workaround. So I'll assign a logging category to the warning for circular toctree.

[asmeurer]

Thanks. I think the self idea would fix it for me, assuming that is also an argument to the toctree function that I use in the template. I see why being circular could cause issues if something assumes there are no cycles.

[tk0miya]

At present, you can make a cycle. So it causes a crash, broken navigation and so on. So I'd like to promote the warning to an error in future.

[asmeurer]

This doesn't seem to be working.

I just tried enabling this

diff --git a/docs/Makefile b/docs/Makefile
index 1ec107d..4a490d1 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -3,7 +3,7 @@

 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
diff --git a/docs/conf.py b/docs/conf.py
index 2aa1f33..8dc8d22 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -61,6 +61,9 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 # Make sphinx give errors for bad cross-references
 nitpicky = True

+suppress_warnings = ['toc.circular']
+
+

 # -- Options for HTML output -------------------------------------------------

But when I build my documentation, I get an error

Warning, treated as error:
/Users/aaronmeurer/Documents/ndindex/docs/index.md:self referenced toctree found. Ignored.

[asmeurer]

When I build without -W I get /Users/aaronmeurer/Documents/ndindex/docs/index.md: WARNING: self referenced toctree found. Ignored., which suggests that it is matching. But the warning isn't being ignored properly when warnings are turned into errors.

[asmeurer]

And just to clarify, the index.md is because I'm using MyST, but I also tried using an index.rst with the same toctree and I got the same issue.

[asmeurer]

I guess the "ignored" part is always part of that warning. So the issue here is that "self referenced toctree" warnings are not included in the "toc.circular" suppress_warnings. There are other warnings like /Users/aaronmeurer/Documents/ndindex/docs/index.md: WARNING: circular toctree references detected, ignoring: index <- index which are suppressed.