Give the ability to supress 'toctree contains reference to excluded document'

[maksim-petukhov]

Is your feature request related to a problem? Please describe.
I'm generating multiple overlapping documents from a shared set of source rst files like in #9596 and I would like to use warnings-as-errors. I also have only one shared conf.py and control which documents to exclude by passing tags to sphinx-build:

# somewhere in conf.py

exclude_patterns = []

if tags.eval_condition('not include_statistics'):
    exclude_patterns.append('kernel/statistics.rst')

The problem is that I include statistics.rst in toctree and sphinx triggers a warning 'toctree contains reference to excluded document', but this warning doesn't have type and subtype so I can supress it. It is not an error, it was excluded intentionally, I want statistics.rst to be in toctree because there is another document which uses include_statistics tag and I that's why I don't want warning here.

Describe the solution you'd like

It could be special metadata field :maybe_excluded: which you can set for toctree entry to supress warning inplace only:

.. toctree::

    :maybe_excluded:statistics
    first_doc
    second_doc

Describe alternatives you've considered

Passing a type and subtype argument to logger.warning so I can supress it in conf.py globally (not so good, because they can be useful).

Now I have to patch toctree directive and override it in my extrension to supress this warning (very bad).

[tk0miya]

-1 for adding a tag to the entry of toctree. But I can accept to make the warnings suppressible via suppress_warnings, instead.

[maksim-petukhov]

@tk0miya implementation from #9628 will supress 'toctree contains reference to nonexisting document' warnings too though they are very useful. And what is bad about adding a tag to the entry of toctree? We've already have :orphan: tag. I can have documents that were excluded by accident and if I suppress all 'toctree contains reference to excluded document' it would be hard to figure it out (= "runtime error"). Wouldn't it be better to know it without browsing the document (having warning = "compile time error")?

[tk0miya]

Finally, I determined to merge #9628 after separating the warning type toc.excluded from toc.not_readable.

And what is bad about adding a tag to the entry of toctree?

There is no mechanism to tag the entry of toctree. So we need to implement the tagging system before suppressing. I think it's very larger than modifying suppress_warnings.

[nanjekyejoannah]

I also need to suppress this warning, what fix was suggested here. I used both toc.excluded and toc.not_readable in vain.

WARNING: autosummary references excluded document

[tk0miya]

@nanjekyejoannah It seems another topic. Could you file a new issue, please?