Allow regex in toctree directive.

[mjstahlberg]

:glob: is pretty useful, but it doesn't seem to enable the following:

• Include all documents named package.[…] but don't include any documents named package.[…].[…].

The reverse selection of only including documents that begin with package and contain two dots can be made with package.*.*. I tried package.[!.]* but the [!.] seems to not interact with the * but only affect a single character.

I propose the addition of a :regex: option to the toctree directive using Python's builtin regex package. It should be relatively easy to implement and work around any shortcomings of :glob: that users might encounter.

[tapaswenipathak]

Hi folks: Can I please take the ticket and PR?

[rayzchen]

Is this ever going to be implemented?

[astrojuanlu]

Duplicate of #4319, and overlapping with #9969.

I came here after looking for a way to exclude patterns from a toctree glob too. The documentation says this:

sphinx/doc/usage/restructuredtext/directives.rst

Lines 1281 to 1284 in a10f733

	.. [#] A note on available globbing syntax: you can use the standard shell
	constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
	these all don't match slashes. A double star ``**`` can be used to
	match any sequence of characters *including* slashes.

However, I didn't see any exclamation marks in glob_re here, so I'm unsure if the documentation reflects the reality:

sphinx/sphinx/directives/other.py

Line 32 in a10f733

glob_re = re.compile(r'.*[*?\[].*')

At least it seems that the documentation could be clarified? But I don't understand what globbing syntaxes are supported. I guess the real work is being done in sphinx.util.matching, which does check for exclamation signs in the pattern.