Issue #1071 resolved

provide a way to exclude a built file from the toctree without warning

Chris Jerdonek
created an issue

Currently, it doesn't seem like there is a way to exclude a built file from the toctree without a warning.

There is the unused_docs/exclude_patterns configuration setting, but that setting suppresses the toctree warning by not building the file at all.

Excluding but still building a file is useful if you would like to "deprecate" a documentation page without breaking already-existing links on the web. The page will still be navigable via a direct link, though the page will not necessarily be navigable from the documentation itself. The content of such a deprecated page could be, for example, "this content has moved to ...."

This use-case came up in the discussion of CPython's issue 16406.

Comments (5)

  1. Chris Jerdonek reporter

    Yes, thank you.

    Before closing this issue though, I would recommend making this option easier to find (e.g. when reading about toctree). For example, you could mention and link to it after the following sentences in the toctree documentation (which also discusses "unused_docs", which incidentally should be changed to "exclude_patterns" since unused_docs is deprecated):

    "In the end, all documents in the source directory (or subdirectories) must occur in some toctree directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation."

  2. Log in to comment