Repository: numpy/numpy
File: doc/source/conf.py (Python)

Code before:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%B %d, %Y'

# List of documents that shouldn't be included in the build.
#unused_docs = []

# The reST default role (used for this markup: `text`) to use for all documents.
default_role = "autolink"

# List of directories, relative to source directories, that shouldn't be searched
# for source files.
exclude_dirs = []

exclude_patterns = []
if sys.version_info[:2] >= (3, 12):
    exclude_patterns += ["reference/distutils.rst"]

# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = False

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

class LegacyDirective(Directive):
    """
    Adapted from docutils/parsers/rst/directives/admonitions.py

    Uses a default text if the directive does not have contents. If it does,
    the default text is concatenated to the contents.

    See also the same implementation in SciPy's conf.py.
    """
    has_content = True
    node_class = nodes.admonition
    optional_arguments = 1

    def run(self):
        try:
            obj = self.arguments[0]
        except IndexError:
            # Argument is empty; use default text
            obj = "submodule"
        text = (f"This {obj} is considered legacy and will no longer receive "
                "updates. This could also mean it will be removed in future "
                "NumPy versions.")

Review comment (bug):
This bit is my only concern, as it suppresses ALL toc.excluded warnings.  The Sphinx documentation related to this warning is a bit sparse, so I'm not sure how greedy this suppression will be. If it only suppresses the files explicitly listed above (the two we want excluded), then I'm happy with this fix.

I've tried using the `only` and `ifconfig` directives to deal conditional toctree inclusions, but that route will fail because the toctree is read before any conditional statements are applied. 

Code after:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
today_fmt = '%B %d, %Y'

# List of documents that shouldn't be included in the build.
#unused_docs = []

# The reST default role (used for this markup: `text`) to use for all documents.
default_role = "autolink"

# List of directories, relative to source directories, that shouldn't be searched
# for source files.
exclude_dirs = []

exclude_patterns = []
suppress_warnings = []
nitpick_ignore = []

if sys.version_info[:2] >= (3, 12):
    exclude_patterns += [
        "reference/distutils.rst",
        "reference/distutils/misc_util.rst",
    ]
    suppress_warnings += [
        'toc.excluded',  # Suppress warnings about excluded toctree entries
    ]
    nitpicky = True
    nitpick_ignore += [
        ('ref', 'numpy-distutils-refguide'),
        # The first ignore is not catpured without nitpicky = True.
        # These three ignores are required once nitpicky = True is set.
        ('py:mod', 'numpy.distutils'),
        ('py:class', 'Extension'),
        ('py:class', 'numpy.distutils.misc_util.Configuration'),
    ]

# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = False

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False

class LegacyDirective(Directive):
    """
    Adapted from docutils/parsers/rst/directives/admonitions.py