sphinx-doc / sphinx-doc/sphinx

Make it possible to disable numfig for certain elements

Open
#10,316 4 comments 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

Is your feature request related to a problem? Please describe.

Numfig is a useful way to automatically add numbering to many kinds of elements. However, by default it automatically adds numbers to many different kinds of elements, not just Figures. There are many cases where you'd want to number one element (e.g. Figures) but not other elements (e.g., code blocks). It is not currently possible to do this.

Describe the solution you'd like

I'd like to be able to configure numfig to disable automatic numbering for certain directives. For example, something like:

# Only apply numfig numbering to figures and tables
numfig_enabled_classes = ["figure", "table"]

Describe alternatives you've considered

Alternatively you could just "live with" the numbering for all these different types of directives But this creates some awkward patterns (e.g. it adds Listing N before each code block caption, which doesn't make sense if you're following the common pattern of using the caption block to show the file name for a code snippet).

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 numfig's configuration and how it assigns captions to figures, tables, and code blocks. Use the requested enabled-class configuration as the acceptance criterion, with coverage showing figures and tables remain numbered while excluded directives do not.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.