sphinx-doc / sphinx-doc/sphinx

exclusions from globbing

Open
#9,969 1 comment 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Problem description
I have run into a situation that seems not to be handled by sphinx globbing. I have two toctrees that use globbing to define their contents. The intent is two sets of non-overlapping pages, one per toctree. However, I cannot get the globbing to avoid including some pages in both.

Potential solution / feature request
It would be nice to have a mechanism for excluding some patterns in addition to including them. For example, one might be able to write something like the following to include all the docs minus the details:

:glob:
docs/*
!docs/details_*

Recognizing that a leading character to select exclusion (! in this example) might conflict with an existing filename, it seems that there should be an option to redefine it:

:exclusion_char: !

Perhaps all of this is already implemented and I have just never run across it. If not, I hope you will consider the idea, as it would make globbing more broadly useful, especially in situations where moving files about is not possible.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing Sphinx's toctree globbing entry point and the tests covering glob-based toctrees. Determine how inclusion patterns are resolved and how an exclusion syntax could be specified without conflicting with filenames; done means separate toctrees can include and exclude the requested page patterns.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.