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

Chris Jerdonek avatarChris 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 (4)

  1. Chris Jerdonek

    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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.