Invert API docs to point from NG to OG (#1316)

* Add disclaimer to attr NS

* Transplant API docs from attr.s to attrs.define

* Transplant API docs from attr.ib to attrs.field

* Remove stale references to attr.ib

* Fix refs

* Link to glossary

* Explain why

* Links from API docs, too

* Link type annotations for good measure

Author: hynek

.github/PULL_REQUEST_TEMPLATE.md

@@ -25,12 +25,13 @@ If your pull request is a documentation fix or a trivial typo, feel free to dele
     - [ ] If they've been added to `attr/__init__.pyi`, they've *also* been re-imported in `attrs/__init__.pyi`.
 - [ ] Updated **documentation** for changed code.
     - [ ] New functions/classes have to be added to `docs/api.rst` by hand.
-    - [ ] Changes to the signature of `@attr.s()` have to be added by hand too.
+    - [ ] Changes to the signatures of `@attr.s()` and `@attrs.define()` have to be added by hand too.
     - [ ] Changed/added classes/methods/functions have appropriate `versionadded`, `versionchanged`, or `deprecated` [directives](http://www.sphinx-doc.org/en/stable/markup/para.html#directive-versionadded).
           The next version is the second number in the current release + 1.
           The first number represents the current year.
           So if the current version on PyPI is 22.2.0, the next version is gonna be 22.3.0.
           If the next version is the first in the new year, it'll be 23.1.0.
+      - [ ] If something changed that affects both `attrs.define()` and `attr.s()`, you have to add version directives to both.
 - [ ] Documentation in `.rst` and `.md` files is written using [semantic newlines](https://rhodesmill.org/brandon/2012/one-sentence-per-line/).
 - [ ] Changes (and possible deprecations) have news fragments in [`changelog.d`](https://github.com/python-attrs/attrs/blob/main/changelog.d).
 - [ ] Consider granting [push permissions to the PR branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork), so maintainers can fix minor issues themselves without pestering you.

docs/api-attr.rst

@@ -1,6 +1,13 @@
 API Reference for the ``attr`` Namespace
 ========================================
 
+.. note::
+
+   These are the traditional APIs whose creation predates type annotations.
+   They are **not** deprecated, but we suggest using the :mod:`attrs` namespace for new code, because they look nicer and have better defaults.
+
+   See also :doc:`names`.
+
 .. module:: attr
 
 
@@ -9,10 +16,6 @@ Core
 
 .. autofunction:: attr.s(these=None, repr_ns=None, repr=None, cmp=None, hash=None, init=None, slots=False, frozen=False, weakref_slot=True, str=False, auto_attribs=False, kw_only=False, cache_hash=False, auto_exc=False, eq=None, order=None, auto_detect=False, collect_by_mro=False, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True, unsafe_hash=None)
 
-   .. note::
-
-      *attrs* also comes with a serious-business alias ``attr.attrs``.
-
    For example:
 
    .. doctest::
@@ -75,6 +78,9 @@ Core
           ...
       ValueError: x must be positive
 
+.. function:: attrs
+
+   Serious business alias for `attr.s`.
 
 .. function:: define
 

docs/api.rst

@@ -5,24 +5,22 @@ API Reference
 
 *attrs* works by decorating a class using `attrs.define` or `attr.s` and then defining attributes on the class using `attrs.field`, `attr.ib`, or type annotations.
 
-What follows is the API explanation, if you'd like a more hands-on tutorial, have a look at `examples`.
+What follows is the dry API explanation for people who understand how *attrs* works.
+If you'd like a hands-on tutorial, have a look at `examples`.
 
 If you're confused by the many names, please check out `names` for clarification, but the `TL;DR <https://en.wikipedia.org/wiki/TL;DR>`_ is that as of version 21.3.0, *attrs* consists of **two** top-level package names:
 
 - The classic ``attr`` that powers the venerable `attr.s` and `attr.ib`.
 - The newer ``attrs`` that only contains most modern APIs and relies on `attrs.define` and `attrs.field` to define your classes.
-  Additionally it offers some ``attr`` APIs with nicer defaults (for example, `attrs.asdict`).
+  Additionally, some of the APIs that also exist in ``attr`` have nicer defaults (for example, `attrs.asdict`).
 
 The ``attrs`` namespace is built *on top of* ``attr`` -- which will *never* go away -- and is just as stable, since it doesn't constitute a rewrite.
-To keep repetition low and this document at a reasonable size, the ``attr`` namespace is `documented on a separate page <api-attr>`, though.
+To keep repetition low and this document at a reasonable size, the ``attr`` namespace is `documented on a separate page <api-attr>`.
 
 
 Core
 ----
 
-.. autodata:: attrs.NOTHING
-   :no-value:
-
 .. autofunction:: attrs.define
 
 .. function:: mutable(same_as_define)
@@ -94,6 +92,10 @@ Core
       C(x=[1, 2, 3], y={1, 2, 3})
 
 
+.. autodata:: attrs.NOTHING
+   :no-value:
+
+
 Exceptions
 ----------
 

docs/examples.md

@@ -17,7 +17,7 @@ True
 False
 ```
 
-So in other words: *attrs* is useful even without actual attributes!
+So in other words: *attrs* is useful even without actual {term}`fields <field>`!
 
 But you'll usually want some data on your classes, so let's add some:
 

docs/names.md

@@ -19,10 +19,10 @@ We recommend our modern APIs for new code:
 - and {func}`attrs.field()` to define an attribute.
 
 They have been added in *attrs* 20.1.0, they are expressive, and they have modern defaults like slots and type annotation awareness switched on by default.
-Sometimes they're referred to as *next-generation* or *NG* APIs.
+Sometimes, they're referred to as *next-generation* or *NG* APIs.
 As of *attrs* 21.3.0 you can also import them from the `attrs` package namespace.
 
-The traditional APIs {func}`attr.s` / {func}`attr.ib`, their serious-business aliases `attr.attrs` / `attr.attrib`, and the never-documented, but popular `attr.dataclass` easter egg will stay **forever**.
+The traditional, or *OG*, APIs {func}`attr.s` / {func}`attr.ib`, their serious-business aliases `attr.attrs` / `attr.attrib`, and the never-documented, but popular `attr.dataclass` easter egg will stay **forever**.
 
 *attrs* will **never** force you to use type annotations.