Improve docs in preparation for release

Author: abravalheri

changelog.d/3068.change.rst

@@ -4,7 +4,7 @@ standards are handled in the ``[tool.setuptools]`` sub-table.
 
 In the future, existing ``setup.cfg`` configuration
 may be automatically converted into the ``pyproject.toml`` equivalent before taking effect
-(as proposed in :issue:`1688`). Meanwhile users can use automated tools like
+(as proposed in #1688). Meanwhile users can use automated tools like
 :pypi:`ini2toml` to help in the transition.
 
 Please note that the legacy backend is not guaranteed to work with

docs/conf.py

@@ -9,6 +9,10 @@
             GH='https://github.com',
         ),
         replace=[
+            dict(
+                pattern=r'(?<!\w)PR #(?P<pull>\d+)',
+                url='{package_url}/pull/{pull}',
+            ),
             dict(
                 pattern=r'(?<!\w)(Issue )?#(?P<issue>\d+)',
                 url='{package_url}/issues/{issue}',
@@ -99,8 +103,6 @@
 github_repo_url = f'{github_url}/{github_repo_slug}'
 github_sponsors_url = f'{github_url}/sponsors'
 extlinks = {
-    'issue': (f'{github_repo_url}/issues/%s', 'issue #%s'),  # noqa: WPS323
-    'pr': (f'{github_repo_url}/pull/%s', 'PR #%s'),  # noqa: WPS323
     'user': (f'{github_sponsors_url}/%s', '@'),  # noqa: WPS323
     'pypi': ('https://pypi.org/project/%s', '%s'),  # noqa: WPS323
     'wiki': ('https://wikipedia.org/wiki/%s', '%s'),  # noqa: WPS323
@@ -170,8 +172,8 @@
 
 # Allow linking objects on other Sphinx sites seamlessly:
 intersphinx_mapping.update(
-    python=('https://docs.python.org/3', None),
     python2=('https://docs.python.org/2', None),
+    python=('https://docs.python.org/3', None),
 )
 
 # Add support for the unreleased "next-version" change notes

docs/userguide/pyproject_config.rst

@@ -12,11 +12,6 @@ Configuring setuptools using ``pyproject.toml`` files
    ``setuptools`` via ``pyproject.toml`` files is still experimental and might
    change (or be removed) in future releases.
 
-.. important::
-   For the time being, you still might require a ``setup.py`` file containing
-   a *arg-less* ``setup()`` function call to support
-   :doc:`editable installs <pip:cli/pip_install>`.
-
 Starting with :pep:`621`, the Python community selected ``pyproject.toml`` as
 a standard way of specifying *project metadata*.
 ``Setuptools`` has adopted this standard and will use the information contained
@@ -106,8 +101,8 @@ Key                       Value Type (TOML)           Notes
 
 Please note that some of these configurations are deprecated or at least
 discouraged, but they are made available to ensure portability.
-New packages should avoid relying on them, and existing packages should
-consider alternatives.
+New packages should avoid relying on deprecated/discouraged fields, and
+existing packages should consider alternatives.
 
 .. tip::
    When both ``py-modules`` and ``packages`` are left unspecified,

docs/userguide/quickstart.rst

@@ -178,7 +178,7 @@ setup also allows you to adopt a ``src/`` layout. For more details and advanced
 use, go to :ref:`package_discovery`.
 
 .. tip::
-   Starting with version 60.10.0, setuptools' automatic discovery capabilities
+   Starting with version 61.0.0, setuptools' automatic discovery capabilities
    have been improved to detect popular project layouts (such as the
    :ref:`flat-layout` and :ref:`src-layout`) without requiring any
    special configuration. Check out our :ref:`reference docs <package_discovery>`
@@ -202,7 +202,7 @@ The following configuration examples show how to accomplish this:
 
         [options.entry_points]
         console_scripts =
-            cli-name = mypkg:some_func
+            cli-name = mypkg.mymodule:some_func
 
 .. tab:: setup.py [#setup.py]_
 
@@ -212,7 +212,7 @@ The following configuration examples show how to accomplish this:
             # ...
             entry_points={
                 'console_scripts': [
-                    'cli-name = mypkg:some_func',
+                    'cli-name = mypkg.mymodule:some_func',
                 ]
             }
         )
@@ -222,10 +222,11 @@ The following configuration examples show how to accomplish this:
     .. code-block:: toml
 
        [project.scripts]
-       cli-name = mypkg:some_func
+       cli-name = mypkg.mymodule:some_func
 
-When this project is installed, a ``cli-name`` executable will be installed and will
-invoke the ``some_func`` in the ``mypkg/__init__.py`` file when called by the user.
+When this project is installed, a ``cli-name`` executable will be created.
+``cli-name`` will invoke the function ``some_func`` in the
+``mypkg/mymodule.py`` file when called by the user.
 Note that you can also use the ``entry-points`` mechanism to advertise
 components between installed packages and implement plugin systems.
 For detailed usage, go to :doc:`entry_point`.
@@ -268,9 +269,9 @@ The example bellow show how to configure this kind of dependencies:
         ]
         # ...
 
-Each dependency is represented a string that can optionally contain version requirements
+Each dependency is represented by a string that can optionally contain version requirements
 (e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier),
-and/or conditional environment markers, e.g. ``os_name = "windows"``
+and/or conditional environment markers, e.g. ``sys_platform == "win32"``
 (see :doc:`PyPUG:specifications/version-specifiers` for more information).
 
 When your project is installed, all of the dependencies not already installed
@@ -338,28 +339,11 @@ Here's how to do it::
 This creates a link file in your interpreter site package directory which
 associate with your source code. For more information, see :doc:`development_mode`.
 
-..
-    TODO: Restore the following note once PEP 660 lands in setuptools.
-    tip: Prior to :ref:`pip v21.1 <pip:v21-1>`, a ``setup.py`` script was
-    required to be compatible with development mode. With late
-    versions of pip, any project may be installed in this mode.
-
 .. tip::
-    If you are experimenting with :doc:`configuration using
-    <pyproject_config>`, or have version of ``pip`` older than :ref:`v21.1 <pip:v21-1>`,
-    you might need to keep a ``setup.py`` file in file in your repository if
-    you want to use editable installs (for the time being).
-
-    A simple script will suffice, for example:
-
-    .. code-block:: python
 
-        from setuptools import setup
-
-        setup()
-
-    You can still keep all the configuration in :doc:`setup.cfg </userguide/declarative_config>`
-    (or :doc:`pyproject.toml </userguide/pyproject_config>`).
+    Prior to :ref:`pip v21.1 <pip:v21-1>`, a ``setup.py`` script was
+    required to be compatible with development mode. With late
+    versions of pip, any project may be installed in this mode.
 
 
 Uploading your package to PyPI
@@ -397,7 +381,8 @@ up-to-date references that can help you when it is time to distribute your work.
 .. rubric:: Notes
 
 .. [#setup.py]
-   The ``setup.py`` file should be used only when absolutely necessary.
+   The ``setup.py`` file should be used only when custom scripting during the
+   build is necessary.
    Examples are kept in this document to help people interested in maintaining or
    contributing to existing packages that use ``setup.py``.
    Note that you can still keep most of configuration declarative in