Address PR review feedback on docstring migration.

Move contributor notes back to source comments, remove deprecated
STATSMAILER_RCPTS docs, and fix the ftp_local_filename cross-reference.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/contributing.rst

@@ -308,17 +308,6 @@ In any case, if something is covered in a docstring, use the
 documentation instead of duplicating the docstring in files within the
 ``docs/`` directory.
 
-When adding a new setting to ``scrapy/settings/default_settings.py``:
-
-* add it in alphabetical order, with the exception that enabling flags and
-  other high-level settings for a group should come first in their group
-  and pairs like host/port and user/password should be in the usual order
-* group similar settings without leaving blank lines
-* add its documentation to :doc:`topics/settings`
-
-When adding a new exception or signal, document it in :doc:`topics/exceptions`
-or :doc:`topics/signals`, respectively.
-
 Documentation updates that cover new or modified features must use Sphinx’s
 :rst:dir:`versionadded` and :rst:dir:`versionchanged` directives. Use
 ``VERSION`` as version, we will replace it with the actual version right before

docs/topics/download-handlers.rst

@@ -378,6 +378,8 @@ This handler supports ``ftp://host/path`` FTP URIs.
 
 It's implemented using :mod:`twisted.protocols.ftp`.
 
+.. _topics-ftp-request-meta:
+
 FTP connection parameters can be passed using :attr:`Request.meta
 <scrapy.Request.meta>`:
 

docs/topics/exceptions.rst

@@ -7,11 +7,6 @@ Exceptions
 .. module:: scrapy.exceptions
    :synopsis: Scrapy exceptions
 
-.. note::
-
-   When adding a new exception to ``scrapy.exceptions``, document it on this
-   page.
-
 .. _topics-exceptions-ref:
 
 Built-in Exceptions reference

docs/topics/leaks.rst

@@ -182,13 +182,6 @@ scrapy.utils.trackref module
 
 Here are the functions available in the :mod:`~scrapy.utils.trackref` module.
 
-.. note::
-
-   PyPy uses a tracing garbage collector, so objects may remain in
-   ``live_refs`` longer than expected, even after they go out of scope. If
-   deterministic behavior is required, you may need to explicitly trigger
-   garbage collection or call ``trackref.live_refs.clear()``.
-
 .. class:: object_ref
 
     Inherit from this class if you want to track live

docs/topics/request-response.rst

@@ -721,7 +721,7 @@ Those are:
 * :reqmeta:`download_timeout`
 * ``ftp_password`` (See :setting:`FTP_PASSWORD` for more info)
 * ``ftp_passive`` (See :setting:`FTP_PASSIVE_MODE` for more info)
-* ``ftp_local_filename`` (See :ref:`topics-download-handlers` for more info)
+* ``ftp_local_filename`` (See :ref:`topics-ftp-request-meta` for more info)
 * ``ftp_user`` (See :setting:`FTP_USER` for more info)
 * :reqmeta:`give_up_log_level`
 * :reqmeta:`handle_httpstatus_all`

docs/topics/settings.rst

@@ -2056,18 +2056,6 @@ Example:
 
 .. note:: This is a :ref:`pre-crawler setting <pre-crawler-settings>`.
 
-.. setting:: STATSMAILER_RCPTS
-
-STATSMAILER_RCPTS
------------------
-
-Default: ``[]``
-
-A list of email addresses to receive a message with scraping stats when a
-spider finishes. Used by the deprecated
-:class:`~scrapy.extensions.statsmailer.StatsMailer` extension, which is enabled
-when this setting is non-empty.
-
 .. setting:: STATS_CLASS
 
 STATS_CLASS

docs/topics/signals.rst

@@ -16,10 +16,6 @@ deliver the arguments that the handler receives.
 You can connect to signals (or send your own) through the
 :ref:`topics-api-signals`.
 
-.. note::
-
-   When adding a new signal to ``scrapy.signals``, document it on this page.
-
 Here is a simple example showing how you can catch signals and perform some action:
 
 .. code-block:: python

docs/topics/spiders.rst

@@ -787,11 +787,6 @@ SitemapSpider
     SitemapSpider allows you to crawl a site by discovering the URLs using
     `Sitemaps`_.
 
-    .. note::
-
-       The :mod:`scrapy.utils.sitemap` module provides sitemap parsing support
-       for this spider. Its API is subject to change without notice.
-
     It supports nested sitemaps and discovering sitemap urls from
     `robots.txt`_.
 

scrapy/exceptions.py

@@ -1,3 +1,6 @@
+# These exceptions are documented in docs/topics/exceptions.rst. Please don't add
+# new exceptions here without documenting them there.
+
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any

scrapy/settings/default_settings.py

@@ -1,3 +1,11 @@
+# Scrapy developers, if you add a setting here remember to:
+#
+# * add it in alphabetical order, with the exception that enabling flags and
+#   other high-level settings for a group should come first in their group
+#   and pairs like host/port and user/password should be in the usual order
+# * group similar settings without leaving blank lines
+# * add its documentation to docs/topics/settings.rst
+
 import sys
 from importlib import import_module
 from pathlib import Path

scrapy/signals.py

@@ -1,3 +1,6 @@
+# These signals are documented in docs/topics/signals.rst. Please don't add new
+# signals here without documenting them there.
+
 engine_started = object()
 engine_stopped = object()
 scheduler_empty = object()

scrapy/utils/sitemap.py

@@ -1,3 +1,6 @@
+# The main purpose of this module is to provide support for the SitemapSpider,
+# its API is subject to change without notice.
+
 from __future__ import annotations
 
 import warnings

scrapy/utils/trackref.py

@@ -1,3 +1,8 @@
+# PyPy uses a tracing garbage collector, so objects may remain in live_refs
+# longer than expected, even after they go out of scope. If deterministic
+# behavior is required, you may need to explicitly trigger garbage collection
+# or call trackref.live_refs.clear().
+
 from __future__ import annotations
 
 from collections import defaultdict