search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.55k stars 2.12k forks source link

Allow regex in toctree directive. #6650

Open Viech opened 5 years ago

Viech commented 5 years ago

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

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 commented 5 years ago

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

rayzchen commented 3 years ago

Is this ever going to be implemented?

astrojuanlu commented 2 years ago

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:

https://github.com/sphinx-doc/sphinx/blob/a10f7338117212b7f3601288b762cb8ba5b67e24/doc/usage/restructuredtext/directives.rst?plain=1#L1281-L1284

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

https://github.com/sphinx-doc/sphinx/blob/a10f7338117212b7f3601288b762cb8ba5b67e24/sphinx/directives/other.py#L32

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.