Improve docs

docs/userguide/extension.rst

@@ -84,36 +84,42 @@ Adding Custom Build Steps
 -------------------------
 
 For simple scenarios where you want to add custom steps to the build process,
-you can create new ``build`` sub commands, by defining
-``setuptools.sub_commands.build`` entry-points that represent sub classes of
+you can create new ``build`` sub-commands, by defining new
+``setuptools.build_steps`` entry-points that represent sub-classes of
 ``setuptools.Command``. For example:
 
-.. code-block:: ini
+.. tab:: pyproject.toml
+
+    .. code-block:: toml
 
-   # setup.cfg
-   [options.entry_points]
-   setuptools.sub_commands.build =
+       # ...
+       [project.entry-points."setuptools.build_steps"]
        build_js = mypkg.myextension:BuildJs
 
+.. tab:: setup.cfg
+
+    .. code-block:: ini
+
+       # ...
+       [options.entry_points]
+       setuptools.build_steps =
+           build_js = mypkg.myextension:BuildJs
+
 .. code-block:: python
 
     # mypkg/myextension.py
     class BuildJs(setuptools.Command):
-        after = "build_ext"
-
         def initialize_options(self):
             self.build_lib = None
             self.build_temp = None
-            self.force = None
             self.editable_mode = False
 
         def finalize_options(self):
             # Copy attributes from the ``build`` parent command
-            options = ('build_lib', 'build_temp', 'force')
+            options = ('build_lib', 'build_temp')
             self.set_undefined_options('build', *zip(options, options))
-            # Now the object has access to the ``self.build_lib``,
-            # ``self.build_temp`` and ``self.force`` attibutes,
-            # inherited from the ``build`` command.
+            # Now the object has access to the ``self.build_lib`` and
+            # ``self.build_temp`` attibutes, inherited from the ``build`` command.
             #
             # ``build_lib`` is effectively the "root build directory"
             # i.e. where the distribution files are going to be placed
@@ -127,25 +133,40 @@ you can create new ``build`` sub commands, by defining
 
         def get_source_files(self) -> List[str]:
             return [...]
-            # ... list the paths for the JavaScript files before bundling/transpilling
+            # ... list the paths for the JavaScript files before bundling/transpiling
 
         def get_outputs(self) -> List[str]:
             return [...]
-            # ... list the paths produced after bundling/transpilling
+            # ... list the paths produced after bundling/transpiling
 
-If defined by sub command class, the following (optional) attributes will be
+If defined by the sub-command class, the following (optional) attributes will be
 considered:
 
-- ``after`` or ``before`` (:obj:`str`): name of another (already defined) sub
-  command. Out of the box, the order ``build`` sub commands run is:
-  ``build_py``, ``build_clib``, ``build_ext`` and ``build_scripts`` and
-  when not specified, the new sub command is placed at the end of this list.
+- ``priority`` (:obj:`int`): Will be used to sort the available entry-points.
+  When two entry-points have the same name, the one with highest priority
+  supersedes the one with lowest priority. By default, the value ``0`` is used.
 
-- ``condition`` (:obj:`str`): name of a method in the parent command
+- ``condition`` (:obj:`str`): name of a method in the ``build`` command
   class. If this method returns ``False`` the sub command is skipped.
+  By default, no condition is analysed.
   Possible values include: ``has_pure_modules``, ``has_c_libraries``,
   ``has_ext_modules``, ``has_scripts``.
 
+- ``insert_build_step``: Function that is used to insert the custom build step
+  in the exist list of build sub-commands. By default ``list.append`` is used,
+  which means that the build step will be inserted after all built-in
+  ``setuptools`` sub-commands (e.g. ``build_py``, ``build_ext``, ...).
+  If defined, ``insert_build_step`` should be a class or static method that accepts
+  2 arguments: the ``build.sub_commands`` list, and an opaque entry
+  representing the custom build step being inserted:
+
+    .. code-block:: python
+
+       class BuildJs(setuptools.Command):
+             @staticmethod
+             def insert_build_step(steps: List[T], build_js_step: T):
+                 steps.append(build_js_step)
+
 
 Supporting sdists and editable installs in ``build`` sub-commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

setuptools/command/build.py

@@ -30,22 +30,11 @@ def get_sub_commands(self):
         from ``{_BUILD_STEPS_ENTRYPOINT}`` entry-points.
 
         The entry-point value should be a subclass of :class:`Command`.
-        If defined by this class, the following (optional) attributes will be
-        considered:
-
-        - ``priority`` (:obj:`int`): Will be used to sort the available entry-points.
-          When two entry-points have the same named, the one with highest priority
-          supersedes the one with lowest priority. By default, the value ``0`` is used.
-        - ``condition`` (:obj:`str`): name of a method in the parent command
-          class. If this method returns ``False`` the sub command is skipped.
-          By default, no condition is analysed.
-        - ``insert_build_step``: Function that is used to insert the custom build step
-          in the exist list of build sub-commands. By default ``list.append`` is used,
-          which means that the build step will be inserted after all the sub-commands
-          that are built into ``setuptools`` (e.g. ``build_py``, ``build_ext``, ...).
-          If given ``insert_build_step`` should be a class or static method that accepts
-          2 arguments: the ``build.sub_commands`` list, and an entry representing the
-          custom build step being inserted.
+        If defined, the following (optional) attributes will be considered::
+
+            priority, condition, insert_build_step
+
+        See :doc:`userguide/extension` for more details
         """
         if not self._sub_commands_loaded_from_entry_points:
             self._verify_distutils_usage()
@@ -128,7 +117,7 @@ class SubCommand(Protocol):
     """Boolean flag that will be set to ``True`` when setuptools is used for an
     editable installation (see :pep:`660`).
     Implementations **SHOULD** explicitly set the default value of this attribute to
-    ``False``.
+    ``False`` in ``initialize_options``.
     When subcommands run, they can use this flag to perform optimizations or change
     their behaviour accordingly.
     """