Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
maksim-0 opened this issue Sep 10, 2021 · 5 comments · Fixed by #9628
Closed

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

maksim-0 opened this issue Sep 10, 2021 · 5 comments · Fixed by #9628

Comments

@maksim-0
Copy link

@maksim-0 maksim-0 commented Sep 10, 2021

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
Copy link
Member

@tk0miya tk0miya commented Sep 12, 2021

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

@tk0miya tk0miya added the config label Sep 12, 2021
@tk0miya tk0miya added this to the 4.3.0 milestone Sep 12, 2021
tk0miya added a commit to tk0miya/sphinx that referenced this issue Sep 12, 2021
tk0miya added a commit to tk0miya/sphinx that referenced this issue Sep 12, 2021
@maksim-0
Copy link
Author

@maksim-0 maksim-0 commented Sep 13, 2021

@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
Copy link
Member

@tk0miya tk0miya commented Nov 9, 2021

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.

@tk0miya tk0miya closed this in #9628 Nov 9, 2021
tk0miya added a commit that referenced this issue Nov 9, 2021
…uded_document_in_toctree

Close #9623: Allow to suppress warnings on excluded document found in toctree
@nanjekyejoannah
Copy link

@nanjekyejoannah nanjekyejoannah commented Nov 15, 2021

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
Copy link
Member

@tk0miya tk0miya commented Nov 17, 2021

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

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Dec 18, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

3 participants